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About This Manual 


INFORMIX-ESQLlC (Embedded SQL and Tools for C) is designed 
for the C programmer who wants to create custom applications 
with database management and for the advanced INFORMIX-SQL 
user who wants to use C functions in PERFORM forms and ACE 
reports. INFORMIX-ESQLlC contains preprocessors, C libraries, 
and header files that allow you to perform the following 
procedures: 


• 
Embed SQL statements in C programs and routines 
(INFORMIX-ESQLlC) 


• 
Perform DECIMAL and DATE type conversions and 
manipulations 


• 
Use C language utility functions 


• 
Use C functions in ACE reports 


• 
Use C functions in PERFORM forms 


This manual assumes that the reader knows C programming 
and is familiar with the structure of relational databases. 
Chapter 6, "C Functions in ACE and PERFORM," assumes 
that the reader is familiar with the ACE and PERFORM programs 
of INFORMIX-SQL, another member of the Relational Database 
Systems (RDS), Inc., family of products. You can read about 
ACE and PERFORM in the INFORMIX-SQL User Guide. 


The underlying file and indexing structure of the database 
tables created through INFORMIX-ESQLlC or INFORMIX-SQL is 
built on C-ISAM. For more information about this indexed- 
sequential access method, see the C-ISAM Programmer's 
Manual. 


This manual is divided into a table of contents, this preface, 
6 chapters, 12 appendixes, an error message section, and an 
index, as summarized in the following list. 
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Preface 
contains a description of the notational 
conventions used in syntax statements. There 
is also a brief description of the demonstration 
database. 


Chapter 1 
gives an overview of relational databases and 
RDSQL, the RDS extension of the ANSI Stan- 
dard Structured. Query Language, developed by 
IBM. 


Chapter 2 
describes how to write C programs containing 
embedded SQL statements. This chapter 
explains the structure of the C program and 
the inter-relationships among the various 
RDSQL statements. 


Chapter 3 
contains an alphabetized description of each of 
the RDSQL statements that you can use within 
a C program. Use this chapter as a reference 
for syntax and rules concerning the use of 
RDSQL statements. 


Chapter 4 
discusses the data types recognized by RDSQL 
and the relationships between them and C 
language data types. This chapter also con- 
tains detailed descriptions of library functions 
that permit manipulation of DATE and 
DECIMAL type variables.. 


Chapter 5 
describes additional utility C functions for 
string manipulation. 


Chapter 6 
expands your power to customize ACE reports 
and PERFORM screen forms by describing how 
you can enter user-written C functions into 
expressions and control blocks. 


Appendix A 
lists the header files used by INFORMIX-ESQLlC, 
ACE, and PERFORM. 


Appendix B 
describes the system catalogs that form the 
data dictionary for a database. 
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Appendix C 
describes the environment variables used by 
INFORMIX-ESQL/C. 


Appendix D 
lists the reserved words that cannot be used as 
RDSQL identifiers (the names of tables, 
columns, or indexes). 


Appendix E 
describes the stores demonstration database 
used in this manual. 


Appendix F 
describes the bcheck utility command sup- 
plied with INFORMIX-ESQL/C, which checks and 
restores the integrity of your index files. 


Appendix G 
describes the sqlconv utility that converts 
databases created by INFORMIX into databases 
that can be used with RDSQL. 


Appendix H 
describes the dbupdate utility that converts 
databases created with Version 1.1 of 
INFORMIX-ESQLlC to databases that can be 
used with Version 2.0 and above. 


Appendix I 
describes the dbload utility that allows you to 
load ASCII files into an RDSQL database. 


Appendix J 
extends the description in Chapter 1 of outer 
joins. 


Appendix K 
describes the dbschema utility that you can 
use to recreate the schema, or data and index 
definitions, for your database. 
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Differences Between ESQL/C Version 2.1 and 
Earlier Versions 


Between Version 2.1 and 2.0. 
INFORMIX-ESQL/C Version 2.1 
contains the following enhancements: 


• 
You can buffer rows that are INSERTed into tables or 
SELECTed from tables. The following RDSQL statements 
support buffering: DECLARE, OPEN, FETCH, INSERT, 
PUT, FLUSH and CLOSE. 


• 
You can specify the starting position and order that rows 
are FETCHed from a table. 


• 
SELECTs (joins) on tables where the indexes do not exist 
on the joined columns are done more efficiently. 


• 
More.flexibility is provided in the UPDATE statement. In 
addition, you can use a more concise syntax. 


• 
You can use the ALTER INDEX statement to organize the 
physical order of rows in a table to match the indexed order. 


• 
You can control the strategy for handling locked records 
with the SET LOCK MODE statement. 


• 
An additional utility program is included with Version 2.l. 
dbscherna allows you to save and recreate the database 
definitions and structure. 


None of these enhancements affect statements written with an 
older version of RDSQL. 
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Differences between Version 2.0 and 1.1. 
The following 
enhancements were implemented: 


• 
Transactions and database recovery 
• 
Views 
• 
Support for NULL values 
• 
UNIONs between SELECT statements 
• 
Additional access control using the GRANT statement 
• 
Support for synonyms 
• 
Access to the ROWID of a row 
• 
Outer joins in SELECT 


9 


Syntax Conventions 


The following legend explains how to interpret the listings of 
statement syntax that appear in this manual: 


ABC 
Any term in the syntax in uppercase letters is a 
keyword. Enter it exactly as shown, disregarding 
case. For example, 


CREATE INDEX indname 


means you must enter CREATE INDEX or create 
index without adding or deleting spaces or letters. 


abc 
Substitute a value for any term that appears in 
lowercase italic letters. In the previous example, 
you should substitute a value for indname. In each 
statement description, a section labeled "Explana- 
tion" describes what values you can substitute for 
italicized terms. 


( ) 
Enter parentheses as shown. They are part of the 
syntax of a statement, not special symbols. 


[ ] 
Do not enter brackets as part of an INFORMIX-ESQL/C 
statement; they surround any part of a statement 
that is optional. For example, 


CREATE [UNIQUE] INDEX 


indicates that you can enter either CREATE INDEX 
or CREATE UNIQUE INDEX. 


The vertical bar indicates a choice among several 
options. For example, 


[ONE I TWO [THREE] I FOUR] 


means that you can enter either ONE or TWO or 
FOUR and that, if you enter TWO, you can also 
enter THREE. 
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, 
I 
I 
I 
'\Then you must choose one of several options, the 
options are enclosed in braces and separated by 
vertical bars. For example, 


:ONE I TWO I THREE: 


means that you must enter ONE or TWO or THREE 
and that you must not enter more than one of them. 


( 


ABC 
When one of several options is the default option, it 
appears underlined. For example, 


[CHOCOLATE I VANILLA I STRAWBERRYj 


means that you can select any of the three options, 
but that if you do not enter one of them, VANILLA is 
the default. 


Enter additional items like those preceding the 
ellipsis, if you choose. The ellipsis indicates that 
the immediately preceding item can be repeated 
indefinitely. For example, 


statement 


means that a series of statements can follow the one 
listed. 


11 


Preparing to Use INFORMIX-ESQL/C 


This section explains the steps you must follow before running 
INFORMIX-ESQLlC (Embedded SQL and Tools for C) and shows 
you how to create the demonstration database. This section 
assumes that INFORMIX-ESQL/C is installed on your computer 
according to the installation instructions in the letter that 
comes with this package. 


As you follow the instructions below, you will notice several 
different typefaces. The characters you type appear in a com- 
puter typeface that looks like this. Words for which you must 
supply values appear in italics like this. 


Setting Environment Variables in UNIX 


Before you can use INFORMIX-ESQLlC you must set the following 
environment variables: 


INFORMIXDIR 
is the directory where INFORMIX-ESQLlC 
resides. 


PATH 
is the search path for programs you want to 
execute. 


You can set these environment variables at the system prompt 
or in your .profile (Bourne shell) or .login (C shell) file. If 
you set these variables at the system prompt, you must reassign 
them the next time you log onto the system. If you set these 
variables in your .profile or .login file, UNIX assigns them 
automatically every time you log onto the system. 


1. Log in. 


2. Set the INFORMIXDIR environment variable. The follow- 
ing instructions assume that INFORMIX-ESQL/C resides in the 
directory /usr/informix. If, for some reason, INFORMIX- 
ESQLlC resides in another directory, substitute the new 
directory name for /usr/informix. 
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If you use the Bourne shell, enter 


INFORMIXDIR=/usr/informix 
export 
INFORMIXDIR 


If you use the C shell, enter 


setenv 
INFORMIXDIR lusr/informix 


3. Include the directory containing INFORMIX·ESQL/C in your 
PATH environment variable. 


If you use the Bourne shell, enter 


PATH=$PATH:$INFORMIXDIR/bin 
export 
PATH 


If you use the C shell, enter 


setenv PATH $(PATH) :$(INFORMIXDIR)/bin 


In addition to the environment variables listed above, you can 
assign other environment variables by following the instruc- 
tions in Appendix C. 


Setting Environment Variables in DOS 


Before you can use INFORMIX·ESQL/C, you must follow these 
steps: 


• 
Set the INFORMIXDIR environment variable if INFORMIX- 
ESQL/C resides in a directory other than \informix. 


• 
Use the PATH command to cause PC-DOS to search 
\informix\bin for executable programs. 


• 
Set the FILES variable to 20 (or more) and the BUFFERS 
variable to 8 (or more) in your CONFIG.SYS file. 


You can set the INFORMIXDIR environment variable and run 
the PATH command at the operating system prompt or include 
them in your AUTOEXEC.BAT file. If you execute them at 
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the system prompt, you will have to execute them again the 
next time you boot the system. If you include these commands 
in your AUTOEXEC.BAT file, PC-DOS assigns them 
automatically every time you start the system. 


1. Turn your system on (if not already on). 


2. If INFORMIX-ESQL/C resides in a directory other than 


\informix, set the INFORMIXDIR environment variable 
by entering 


set 
INFORMIXDIR=di rnarne 


where dirname is the name of the new directory. 


3. Use the PATH command to cause PC-DOS to search the 
\informix\bin directory for executable programs: 


PATH 
\ i n for rn i x \ bin [ ; d i r n arne 
... J 


You can specify a device name before the full directory path 
if required. The square brackets indicate an optional part 
of the command. Do not enter the brackets if you want to 
include other directories in the search path. Also, make 
sure you enter a semicolon between separate path names. 


4. Use your system editor to assign the following values to 
FILES and BUFFERS in your CONFIG.SYS file: 


FILES=20 
BUFFERS=8 


After you save the changes, reboot your computer. If you 
did not include the INFORMIXDIR variable and the PATH 
command in your AUTOEXEC.BAT file, you must reas- 
sign them when you restart the system. 


In addition, you can assign other environment variables by 
following the instructions in Appendix C. 
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Getting Started with INFORMIX-ESQL/C on 
DOS Systems 


To start working with INFORMIX-ESQL/C on DOS systems, be 
sure that your computer is up and running, and that the 
operating system prompt appears on your screen. 


To compile or execute programs that use INFORMIX-ESQLlC, you 
must perform two steps: 


1. Load the database agent. The database agent is the part of 
INFORMIX-ESQL/C that performs the data access and file- 
manipulation tasks necessary to complete your database 
management operations. 


2. Compile and run your INFORMIX-ESQL/C programs. 


Loading the Database Agent 


To load the database agent, enter 


startsql 


You need to execute this command only once per session. 
The database agent remains in memory until you execute the 
command 


exit 


from the command line. When you execute this command, it 
removes the database agent from memory. Because the data- 
base agent requires space in memory, you should remove it 
when you have completed all the desired INFORMIX-ESQL/C 
operations. This frees memory for running other programs on 
your system. 


If you attempt to load the database agent when it is already 
installed in memory, INFORMIX-ESQL/C issues the message 
STARTSQL has already been executed. 
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Entering INFORMIX-ESQLIC 


After you have loaded the database agent, enter 


esql 
If you try to run esql without first loading the database agent, 
INFORMIX-ESQL/C issues the message Please run STARTSQL. 


If you want to check to see if the database agent has been 
loaded, enter 


set 


This gives you a list of your environment variables. If the 
database agent has been loaded, the variable SQLCADDR is 
listed. The following is an example of SQLCADDR as it 
appears in a list of environment variables. The numbers 
represent the address in memory where the database agent is 
loaded. 


SOLCADDR=333744a8 
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The Demonstration Database 


The INFORMIX-ESQLlC package includes a demonstration 
database. Most of the examples in this manual are based on 
the stores demonstration database. This database, described 
and listed in detail in Appendix E, is concerned with the custo- 
mers of, and the orders placed with, a wholesaler of sports 
equipment. You can create the stores database in the current 
directory by typing esqldemo. This shell script removes any 
database labeled stores and installs the demonstration 
database and the example programs used in this manual. 


The stores database contains five tables: 


customer 


orders 


items 


stock 


manufact 


contains information about the retail stores 
that are the customers of the wholesaler. 


contains information about the orders placed. 


contains information about the individual 
items in each order. 


contains a list of all stock items available from 
the wholesaler. 


contains data on the manufacturer of the stock 
items. 
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Creating the Demonstration Database 


The following instructions tell you how to copy the demonstra- 
tion database into a directory that you select. 


1. Create a new directory for the demonstration database by 
entering 


mkdir 
dirname 


where dirname is the name of the new directory. 


2. Change the current directory to the new directory by 
entering 


cd d i r name 


3. Create the demonstration database byentering 


esqldemo 


This command creates the demonstration database and its 
sample programs, forms, and reports in the current directory. 
If this command does not work, make sure you have set all 
your environment variables correctly. 


You can run this command when you want to restore the 
original demonstration database after making changes. 


Your computer is now ready for you to use INFORMIX-ESQL/C. 


18 The Demonstration Database 


c 


Restricted and Public Databases on UNIX 


In order for INFORMIX-ESQLlC to access a database, the current 
user must have read and execute permissions for each directory 
in the database pathname. (The RDSQL GRANT and REVOKE 
statements apply only to tables within a database, not to the 
database itself.) 


1. You can restrict access to the database to yourself by typing 
the following command: 


chmod 
700 dirname 


where dirname is the directory containing the database. 


2. You can make the database accessible to all users by typing 
the following command: 


chmod 
755 dirname 


assuming that all directories above dirname have at least 
the same permissions. 
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Chapter Overview 


Relational Database Systems, Inc.. (RDS) has developed RDSQL 
as an extension of the ANSI Standard Structured Query 
Language (SQLl developed by IBM. The additions that RDS 
has made to the language permit you to change databases. 
change the names of tables and columns. and increase the 
functionality of ANSI standard SQL statements. 


In the family of RDS database products. RDSQL plays se\'eral 
roles. In Il\"FOR:mX-SQL. RDSQL is both the interactive query 
language and the language you use to choose the data for ACE, 
the Il\"FOR:\HX-SQL report -writing program. You can read about 
these uses ofRDSQL in the INFORMIX·SQL l'..,er Manual. In 
Il\"FOR:\HX-ESQLlC, RDSQL is the database query language that 
you embed in C programs to create an application. 


This chapter describes RDSQL and gives an overview of its 
statements. You can read about the full syntax and rules 
gm'erning the RDSQL statements that you can use in Il\"FOR:\HX- 
ESQLlC in Chapter 3. The statements are organized alphabeti- 
cally. The syntax displays use the conventions defined in the 
Preface. The statements described in Chapter;) are not identi- 
cal to those described in Chapter 2 of the INFORMIX·SQL 
Reference Manual. The differences reflect the change in appli- 
cation between Il\"FOR:\HX-ESQLlC and I:\"FOIC\HX-sQL-that is. 
between the programming use and the interactive use. 
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Relational Databases 


The statements of RDSQL create and manipulate relational 
databw;cs. A relational database consists of one or more tables 
that. in turn. are constructed of roU"s and columns. Each row 
contains a particular set of column values. Databases are 
created as subdirectories of the current directory. The name of 
the subdirectory is the database name with the extension .dbs. 
The database subdirectory contains nine system catalog tables 
that define the database dictionary. It also contains the tables 
that constitute the database. Each of these tables is repre- 
sented by data files and index files with the extensions .dat and 
.idx. respectively. The system catalogs are described in 
Appendix B. 


RDSQL Identifiers 


An RDSQL identifier is the name of an object and can consist of 
letters. numbers. and underscores ( 
). The first character 
must be a letter. Unless qualified to the contrary. an identifier 
can have from 1 to 18 characters. 


Database 
is a name that can have from 1 to 10 (UNIX) or 8 
(DOS) characters. 


.Table 
is a name that must be unique within the 
database. 


Column 
is a name that must be unique within a table; 
there can be duplicate column names within a 
database. When column names within different 
tables are not unique. use the notation 
table.column to specify the intended column. 


I-G HDSQL Identifiers 


There can be no ambiguity between a C variable and an HDSQL 
identifier. since you must precede C \'ariables that appear in 


RDSQL statements (host \·ariables. see Chapter :2) with a dollar 
sign ($) or a colon (:). For example. if you define lname as a 
host 3;ariable and you want to refer to the database column of 
the same name. use $lname for the host variable name: 


SELECT 
Iname 
INTO $Iname 
FROM customer 


Database Data Types 


You must assign a data type to every column in the database 
(see the CREATE TABLE statement in Chapter 3). Valid data 
types in RDSQL are as follows: 


CHAR(n) 
is a character string of length n (where 1 
<= n <= 32.767), 


SMALLINT 
is a whole number from -3:2.767 to 
+32.767. 


INTEGER 
is a whole number from -2.147.483,647 
to +2,147.483,647. 


DECIMAL[(m[,n])] 
is a decimal floating point number with a 
total of m « 
= 32) significant digits (the 
precision) and n «= m) digits to the 
right of the decimal point (the scale). 
When you give values for both m and n, 
the decimal variable has fixed-point 
arithmetic. All numbers less than 0.5 X 
10-n in absolute value have the value 
zero. The largest absolute value of a 
variable of this type that can be stored 
without an error is lOm-n - 10-n. 


The second parameter is optional and. if 
missing, the variable is treated as a 
floating decimal. This means that 


1-. 


SI\lALLFLOAT 


FLOAT 


1\10NEY[ (m[.n))) 


SERIAL[(Il)] 
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DECIrvlAL(m) \'ariables ha\'e a precision 
of m and a range in absolute \"alue from 


_) ·)S 
]')(, 
10 
-,. to 10 -. If no parameters are 
designated. DECIMAL is treated as 
DECIMALOGL a floating decimal. 


is a binary floating-point number 
corresponding to the float C data type. 
The range of \"alues for a SMALLFLOAT 
data type is the same as the range of 
values for the C float data type on your 
machine. 
On small machines. RDSQL 
implements SMALLFLOAT as 
DECIMAL(8). 


is a binary floating-point number 
corresponding to the double C data type. 
The range of values for a FLOAT data 
type is the same as the range of values 
for the C double data type on your 
machine. On small machines. RDSQL 
implements FLOAT as DECIMAL(lG). 


can take two parameters like the 
DECIMAL data type. The limitation on 
values for columns of type MONEY(m. 
n) is the same as for columns of type 
DECIMAL(m. n). The type MONEY(m) 
is defined as DECIMAL(m. 2) and. if no 
parameter is gi\"en. MONEY is taken to 
be DECIMAL06. 2). Regardless of t.he 
number of parameters. the data type 
MONEY will always be treated as a fixed 
decimal number. 


is a unique sequential integer assigned 
automatically byRDsQL. You can assign 
an initial value n. The default starting 
integer is 1. 


DATE 
is a date entered as a character string in 
one of the formats described in Chapter 4 
and stored as an integer number of days 
since December 31. 1899. 


RDSQL Statement Summary 


There are five different types of RDSQL statements used with 
INFORMIX-ESQLlC: 


• 
Data definition and administration 
• 
Data manipulation 
• 
Cursor management 
• 
Data integrity 
• 
Dynamic management 


Data Definition and Administration 


Data definition and administration statements include those 
that create, drop, and control access to a database and its 
tables, views, synonyms, and indexes, and modif~' or rename 
tables and columns. Of this list, only the DAT.-\BASE state- 
ment is required before manipulating the data of an existing 
database. 


CREATE 
DATABASE 


DATABASE 


creates a database directory, sets up the 
system catalogs, and makes the new data- 
base the current databa.'if'. There can be 
no more than one current database at 
any time. 


selects a database and makes it the 
current database. There can be no more 
than one current database at any time. 
The DATABASE statement has the 
option EXCLLTSI\TE that opens the 


l·~ 


CLOSE 
DATABASE 


. DROP 
DATABASE 


CREATE TABLE 


ALTER TABLE 


database in an exclusive mode and allows 
only the Database Administrator (DBA) 
to have access to the database. This 
option is particularly useful when check- 
ing or archiving the database. 


closes the current database files and 
leaves no database current. The only 


RDSQL statements permitted when there 
is no current database are those in the 
following list: 


• CREATE DATABASE 
• DATABASE 
• DROP DATABASE 
• START DATABASE 


deletes all tables, indexes, system cata- 
logs, and the database subdirectory. If 
no other files are present in the database 
directory, the subdirectory is also deleted. 


creates a table and defines the columns 
and their data types. 


adds and drops columns from a· table and 
modifies data types of existing columns. 


RENAME TABLE 
changes the name of a table. 


DROP TABLE 


CREATE VIEW 
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deletes all data and indexes for a table 
and erases its entry in the system 
catalogs. 


defines a table selected from rows and 
columns of existing tables and views. As 
the underlying tables change, so does the 
view built upon them. See the section 
"Views" later in this chapter for an 
explanation of how to use views. 


DROP VIEW 


CREATE 
SYNONYM 


DROP 
SYNOXYM 


RENAME 
COLUMN 


CREATE INDEX 


DROP INDEX 


ALTER INDEX 


deletes the definition of the vie\",' frum 
the system catalogs along with any \'iews 
defined in terms of the one that is 
dropped. The underlying tables are 
unaffected. 


defines an alternati\'e name for a table or 
a view. A synonym is effective only for 
the user who creates it and can be 
dropped only by its creator. This means 
that if several people want to use the 
same synonym, they must each create the 
synonym. For I~FORMIX·ESQL!Cpro- 
grams, the creator is the user who runs 
the program that creates the synonym. 


deletes a synonym from the system 
catalogs. 


changes the name of a column. 


creates an index on one or more columns 
of a table. 


deletes a previously CREATEd index. 


allows you to modify a table so that the 
rows are in the same order as the index. 
The index is called a clustered index. 


See the section "Indexing Strategy" later in this chapter for 
more information on indexes. 


A user has access to the database and to specific columns 
within a table only when the DBA or the owner of the table 
specifically grants these privileges. RDSQL provides the 
following statements affecting data access: 


\, 
I 


l 


GRANT 
grants database access privileges to 
specific users or to the public: 
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REVOKE 


UPDATE 
STATISTICS 


DataManipulation 


removes database access privileges from 
specific users or from the public. 


See the section "User Status and 
Privileges" later in this chapter for 
further information. 


updates the system catalogs by determin- 
ing and inserting the number of rows in 
the indicated tables. RDSQL uses this 
information in optimizing queries, but 
does not automatically update the system 
catalogs after each INSERT or 
DELETE. 


( 


The most frequently used statements are the data manipulation 
statements that follow: 


DELETE 


INSERT 


SELECT 


UPDATE 


deletes one or more rows from a table. 


adds one or more rows to a table. 


retrieves data from one or more tables. 


modifies the data in one or more rows of a 
table. 


SELECT is the most important and the most complex state- 
ment in RDSQL. Although its syntax is defined in detail in 
Chapter 3, the following examples illustrate its use. 


select 
Iname, 
company 
into $p_lname, 
$p_company 
from customer 
where 
customer~num = 101 
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This statement queries the customer table and returns the 
single row for which the customer number is 101. From that 
row, it selects and places the values in the columns correspond- 
ing to the contact's last name and company name in the host 
variables p_Iname and p_company. 


select 
quantity, 
total-price 


into $quantity, 
$total-price 


from 
items 
where 
order_num = 
1001 


This statement shows another SELECT statement that returns 
a single row. In this example, the host variables quantity and 
total_price have the same identifier as the corresponding 
columns in the items table. There is no conflict here since the 
prefixed $ distinguishes the column name from the program 
variable. 


A SELECT statement that returns a single row is called a 
singleton SELECT statement and can stand alone. See the 
next section on cursor management for how to handle SELECT 
statements that return more than one row. 


Cursor Management 


In the examples in the previous subsection, the SELECT state- 
ment returned exactly one row, and the values returned to the 
program variables are unambiguous. When more than one row 
can be returned, it is necessary to have a device to distinguish 
one row from another. This device is called a cursor. 


The set of rows returned by a SELECT statement is called the 
active set for the statement. Within an INFORMIX-ESQLlC pro- 
gram, you can work with only one row of the active set at a 
time. This row is called the current row and is referenced by a 
cursor. 


A cursor can be in one of two states: open or closed. When it 
is in an open state, the cursor points to the current row, 
between two rows, before the first row, or after the last row. 
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When it is in a closed state, the cursor no longer is associated 
with an active set. although it remains associated with the 
SELECT statement. 


Use the following RDSQL statements to define and manipulate a 
cursor: 


DECLARE 


OPEN 


FETCH 


CLOSE 


names the cursor and associates it with a 
particular SELECT statement. 


puts the cursor in an open state with regard to 
the SELECT statement. The OPEN state- 
ment causes the SELECT statement to be run 
with the current program variables and leaves 
the cursor pointing just before the first row of 
the resulting active set. While the cursor is in 
an open state. subsequent changes of the 
program variables do not affect the active set. 


advances the cursor to the next row and 
retrieves the values from that row. If the 
cursor is already beyond the last row, the error 
variable sqlca.sqlcode has the value 
SQLNOTFOUND (= 100). (See "Error Han- 
dling and the sqlca Structure" in Chapter 2.) 
SQLNOTFOUND indicates the end of the 
active list. 


puts the cursor in a closed state and releases 
the active set. No statements referring to the 
cursor, other than OPEN, are now operative. 


You can use a special form of the DELETE statement to 
remove the current row indicated by the cursor. Following the 
DELETE statement, the cursor is left between the previous 
and next rows and cannot be used again until repositioned with 
a FETCH statement. The UPDATE statement allows you to 
modify the current ro\\.< The cursor position does not change 
after an UPDATE statement. 


To illustrate the cursor management statements. consider the 
following examples: 
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$ 
declare 
x cursor 
for 
select 
order_oum, 
order_date 
from orders 
where paid_date 
is null 
and ship_date> $p_date 
for 
update of 
paid_date 


This statement names a cursor x and associates it with the 
SELECT statement following the FOR keyword. The 
SELECT statement returns the order number and order date 
for those unpaid orders whose shipping date was later than the 
date in the host variable p_date. The statement also enables 
a future UPDATE statement to modify the paid_date 
column. The DECLARE statement does not run the query; it 
simply assigns the cursor to the SELECT statement: 


open 
x 


When, later in your program, you use the OPEN statement, it 
uses the value that the program variable p_date has at that 
time and runs the SELECT statement, identifying those rows 
that satisfy the WHERE clause. The cursor x now points to 
just before the first row returned: 


fetch 
x into $order_num, $order_date 


The FETCH statement moves x to point to the first row and 
fills the program variables order_num and order_date with 
the values of the columns order_ num and order_date in 
the first row: 


update orders 
set 
paid~date = TODAY 
where current 
of 
x 


The UPDATE statement changes the value of the date the 
order was paid to today's date in the current (first) row. The 
cursor remains pointing to the first row: 
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close x 


The cursor x is now put into a closed state, and the active set 
is effecti\'ely dissolved. An immediate FETCH statement 
would be an error. since a cursor in a closed state cannot point 
to anything. If, at a later time, you should execute the state- 
ment 


open 
x 


the cursor x would be put back into an open state with a new 
active set that depends upon the value of the program variable 
p_date when the OPEN was executed. 


Scroll Cursors 


You can DECLARE a scroll cursor if you want to FETCH rows 
and control the order of the retrieval. 


You can FETCH rows from the active set in one of two 
directions: the NEXT row in the list (the default FETCH), or 
the PREVIOUS (or PRIOR) row in the list. You can scroll for- 
ward and backward through the active set by issuing a series of 
FETCH NEXT and FETCH PREVIOUS statements. 


In addition, you can FETCH CURRENT (retrieving the 
current row in the active set), FETCH FIRST (retrieving the 
first row in the active set), FETCH LAST tretrieving the last 
row in the active set), FETCH RELATIVE n (retrieving the 
nth row relative to the current cursor position in the active 
set). and FETCH ABSOLUTE m (retrieving the mth row in 
the active set). 


The following example DECLAREs a scroll cursor and 
FETCHes the last row in the active set. 
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$ 
declare 
~curs scrol I cursor 
for 
select 
order_date 
from orders 
where customer_num = 118 


$ 
open 
~curs 


$ 
fetch 
last 
~curs into $order_date 


All FETCH statements except the default FETCH NEXT 
statement require that you first DECLARE a SCROLL cursor. 
The default FETCH statement works with both a scrolling cur- 
sor and a regular cursor. 


You cannot DECLARE a scrolling cursor FOR UPDATE. This 
means you cannot use the WHERE CURRENT OF keywords 
to UPDATE or DELETE a row fetched by a scroll cursor. 


Insert Cursors 


You can associate a cursor with an INSERT statement by 
using it in a DECLARE. The insert cursor permits more 
efficient insertion of data into a database by buffering the data 
in memory and writing to the disk only when the buffer is full. 
This differs from other IBM implementations where the pro- 
grammer has the option to block the input (inserting into a 
buffer) or not. 


Two statements allow you to manipulate the buffer. 


PUT 


FLUSH 


inserts a row into the buffer. 


forces writing of the buffer. 


RDSQL automatically writes the rows to the table whenever the 
buffer is full or the cursor is CLOSEd. You can use FLUSH if 
you want to write out the rows more frequently. 
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Use the regular INSERT statement if you do not want the 
inserts buffered. 


The CLOSE statement flushes the buffer and closes an open 
cursor. If RDSQL encounters an error while flushing the buffer 
to disk, it stops the flushing and does not close the cursor. 
Buffered rows following the last successfully inserted row are 
discarded. Check the values of sqlca.sqlcode for information 
about the source of the problem and sqlca.sqlerrd[2] for the 
number of rows successfully inserted into the database. (See 
the section "Error Handling and the sqlca Structure" in 
Chapter 2 for more information.) 


As noted above, the CLOSE statement not only releases the 
cursor, but it flushes any rows that remain in the insert buffer. 
The FLUSH statement is an RDS extension that forces RDSQL 
to insert the rows in the insert buffer into the database without 
closing the cursor. The cursor remains open for more PUTs. 
You can force the insertion using the FLUSH statement, but 
you cannot delay insertion by not using the FLUSH statement. 
RDSQL automatically flushes the buffer whenever it is full. 
Following a flush, sqlca.sqlerrd[2] is set to a positive numbe"r 
indicating the number of rows physically inserted into the 
database. 


An insert cursor that includes only constants in its values list is 
treated differently. Rows are neither buffered nor written to 
disk a row at a time. Instead, RDSQL maintains a counter indi- 
cating the number of rows to be inserted. The rows inserted 
during that operation are not entered into the database until 
the cursor is closed. At this point, the data is written to disk 
and sqlca.sqlerrd[2] is set to a positive number indicating the 
number of rows physically inserted into the database. 


If your database has transactions, you must include all PUT 
statements within a BEGIN WORK-COMMIT WORK or 
BEGIN WORK-ROLLBACK WORK block. (See the section 
"Data Integrity" immediately following for a discussion of 
transactions.) 


Consider the following advantages and disadvantages of using 
insert cursors: 


• 
If the program does not frequently need to insert rows, the 
overhead of setting up an insert cursor may be greater than 
the increased performance from buffering rows. 
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• 
If you want other programs to be able to retrieve the rows 
immediately after they are PUT into the buffer, you must 
explicitly FLUSH the buffer so that the rows are placed into 
the table. Each FLUSH reduces the advantage of buffering. 
Use the regular INSERT statement if you do not want the 
inserts buffered. 


Caution! Exiting a program without closing the cursor leaves the 
buffer unflushed. Rows inserted into the buffer since the last flush 
are lost. You cannot rely on the end of program to close the cursor 
and flush the buffer. 


While the COMMIT WORK and ROLLBACK WORK statements 
close all open cursors, do not use either statement for this purpose. 
If a COMMIT WORK statement attempts to close more than one 
cursor and fails in this process, you do not know which cursor 
caused the problem or the number of rows inserted into the database. 


Always check the value of the sqlca.sqlcode variable after each 
insert and when you issue a CLOSE statement. 


Data Integrity 


RDSQL provides data integrity in several ways. You can prevent 
users of the database from changing the same row at the same 
time. You do this by explicitly locking a table or by accessing 
the row from within a transaction. You can also guarantee 
data integrity by using the recovery feature, which is imple- 
mented with transactions, or by using audit trails. 


RDSQL provides data integrity by implementing the idea of 
transactions. A transaction is a series of operations on a data- 
base (RDSQL statements) that you want to be completed· 
entirely or not at all. Examples of transactions are abundant in 
bookkeeping where several operations on several different 
accounts must be made as a unit or the books will be out of 
balance. Your INFORMIX-ESQLlC programs can ensure the data 
integrity of your database by using the following statements: 


BEGIN WORK 


COMMIT WORK 


marks the beginning of a transaction. 


marks the end of a transaction by 
authorizing all changes to the data- 
base since the last BEGIN WORK 
statement. 
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ROLLBACK WORK 


START DATABASE 


ROLLFORWARD 
DATABASE 


Transactions 


marks the end of a transaction by 
revoking all changes to the dat~base 
since the last BEGIN WORK 
statement. 


initiates a new transaction log file. 


uses a transaction log file to restore a 
database from backup. 


A transaction is a series of operations on a database (RDSQL 
statements) that you want to be completed entirely or not at 
all. RDSQL provides several statements that give you the ability 
to protect the integrity of your database by treating a transac- 
tion as a unit. 


The first statement is the CREATE DATABASE statement 
including the WITH LOG IN clause. This statement creates 
not only the database but also a transaction log file that keeps 
track of all modifications to the database. 


When you want to perform a series of operations that you 
consider a unit, you issue the BEGIN WORK statement. This 
statement causes all subsequently altered rows of the database 
tables to be locked against modification by others (although 
others may view them). When you are satisfied that the series 
ofoperations has produced the desired results, you terminate 
the transaction with a COMMIT WORK statement. If you are 
not happy with the results, you can terminate the transaction 
with a ROLLBACK WORK statement. This statement 
restores the database to the state that existed when you issued 
the BEGIN WORK statement-with an important exception. 
All database definition statements that alter the number or 
names of tables, the number or names of columns, the data 
types, or the indexes are treated as singleton transactions; that 
is, if they were executed successfully, they are committed and 
are not rolled back. Both the COMMIT WORK and the 
ROLLBACK WORK statements unlock the rows and make 
them accessible for modification by others. 
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The number of rows that can be locked at one time by all users 
is limited. The actual limit depends on your operating system. 
Try to restrict the definition of a transaction to a few state- 
ments that involve only a few rows. If you expect that the 
number of rows entering into the transaction will be large. 
LOCK the tables involved until the transaction is completed. 


Note: The BEGIA' WORK, COMMIT WORK, and ROLLBACK 
WORK statements cannot lwrk unless you ('REA TEd the data- 
base 16th the WITH LOG IN option or STARTed the database 
16th a transaction log file. 
A database created without a 
transaction log is described as a database "without trans- 
actions." 
A database created with a transaction log is 
described as a database "with transactions." 


If you open or create a database with transactions. but do not 
execute the BEGIN \\'ORK statement. RDSQL treats each state- 
ment as a singleton transaction. Each statement. if it executes 
successfully. is committed. and the database is permanently 
altered. If the statement fails. there is an automatic rollback to 
the status before the statement. 


You must execute cursor manipulation statements inside a 
transaction if your database was created or started with 
transactions. You should execute the BEGIN WORK state- 
ment before opening a cursor. The COMMIT \\'ORK and 
ROLLBACK WORK statements close all open cursors. 


You cannot ROLLBACK any of the Data Definition statements 
nor GRANT or REVOKE statements. Do not use these 
statements within a transaction. 


If you create a database without transactions. there is no 
automatic recovery from a situation where you want to treat 
several database operations as a single unit of work. For exam- 
ple. under transactions. you can UPDATE several rows as a 
single unit of work. If the UPDATE fails after changing some 
rows but not all. you can ROLLBACK the transaction to the 
original state where no rows are modified. \\"ithout transac- 
tions. you must take explicit action to restore the updated 
rows. 
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Transaction Log File Maintenance 


The transaction log file can become quite large and, periodi- 
cally, the Database Administrator (DBA) may want to archive 
it on tape and initiate another log file. At the same time, the 
DBA should also create a backup of your database. Generally 
speaking, every logfile must have a corresponding archive copy 
of the database. After backing up the log file and the database, 
the DBA must specify an empty log file. In order to reuse the 
same log file, the DBA can create an empty log file with the 
same name as the old one. In UNIX, you can do this with the 
following command: 


cal 
/dev/null > 
109f i Ie 


In order to change the name of the log file, the DBA must 
execute the START DATABASE statement just before making 
a backup of the database. The START DATABASE statement 
locks the database in EXCLUSIVE MODE while it is operating 
so that no further changes can be made. If START 
DATABASE fails, no database is open. 


If the database is without transactions and you want to use 
transactions, the DBA must execute the START DATABASE 
command just before making a copy of the database. 


If there is a backup copy of the database and a transaction log 
file that begins with the operations executed immediately after 
the backup was made, the DBA can bring the backup database 
up to date with the ROLLFORWARD DATABASE statement. 
This statement recovers the database through the last ter- 
minated transaction. The DBA must load the backup database 
files and execute the ROLLFORWARD DATABASE state- 
ment. After rolling the database forward, the DBA is the only 
one who has access to the database, since it is left in an 
exclusive mode. This state allows the DBA to check the data- 
base for errors before making it generally available. Logging 
does not occur during this checking phase. The DBA must 
close the database when it has been restored correctly. 
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Audit Trails 


An audit trail is a file that contains a history of all additions. 
deletions. updates. and manipulations to a database table. An 
audit trail serves a purpose similar to that of a transaction log: 
each is used to maintain a record of modifications to a data- 
base. and each can be used to update backup copies of a 
database. 


Three audit trail statements are available to protect the 
integrity of a table: 


CREATE AUDIT 


DROP AUDIT 


creates an audit trail for a table. 


removes the audit trail on a table. 


RECOVER TABLE 
restores a table using the audit trail. 


Creating an Audit Trail. 
Use the CREATE AUDIT statement 
to create an audit trail file and to begin writing the audit trail. 
The format is 


CREATE Al'DIT FOR table-name IK "palhnamc" 


where table-name is the name of the table for which you want 
to create an audit trail file and path name is the full pathname 
of the audit trail file. The audit trail file should be on a physi- 
cal device other than the one that holds the data so that a s,'.·s- 
tern failure affecting the device that holds the data does not 
also damage the audit trail. If your computer system has more 
than one hard disk, the audit trails could be written to one of 
the disks not containing the data. 


T() use the audit trail, make a backup copy of the table after 
you have executed a CREATE AUDIT statement but before 
you have made any changes to the table. Once you have 
started the audit trail and have made a backup. you are ready 
to work with the table. 


You can drop and create an audit trail file whenever you want. 
Drop and create the audit trail files just before you make a 
complete backup of the device containing the data file. If a 
system failure should occur, you can use the audit trail to 
backup the table from the time ofthe last backup to the time 
the failure occurred. 


Recovering a Table. 
In the event of a system failure, you can 
use the RECOVER TABLE statement to restore a database 
table by using a backup copy of the table and an audit trail file. 
You must first restore a backup copy of the table. The backup 
copy must be in the original state that it was in when the audit 
trail was started. If it is not in the original state, the recovery 
fails. The format of the recovery statement is 


RECOVER TABLE table-name 


where table-name is the name of the table you want to recover. 


Once you recover the table, use the DROP AUDIT statement 
to remove the contents of the audit trail file. Then run the 
CREATE AUDIT statement to start a new audit trail file. 
Finally, make a new backup copy of the table. 


Comparison of Transactions and Audit Trails 


Transactions provide data integrity in two ways. First, they 
guarantee that RDSQL statements are either successfully com- 
pleted or are completely canceled. If, for example, you update 
several rows of one or more tables within a transaction, the 
entire update is guaranteed either to succeed by updating all 
rows, or to fail without changing any rows. Second, the 
transaction log can be used to recover an entire database. 


Audit trails are associated with individual tables. They do not 
guarantee that modifications to several rows of a table either 
succeed entirely or fail without any effect. An audit trail file 
can be used only to recover the table for which it is created. 


You should consider using audit trails when you have only a 
few critical tables and where you do not need the additional 
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facilities of transactions. In this case, the overhead of logging 
is incurred only when the critical tables are modified. If you 
need to maintain the integrity of the database as a whole, or 
need the guarantee that RDSQL statements are executed as a 
unit either entirely or not at all, you must use transactions. 


Locking Statements 


RDSQL automatically locks a record where integrity problems 
could arise if two or more programs accessed the record simul- 
taneously. Explicit table orrecord locking is generally not 
required. RDSQL allows you to temporarily limit access to a 
table, however, by executing the LOCK TABLE statement. 
You can also specify whether you want your program to fail if a 
record it wants is locked or to wait for the record to become 
available. 


LOCK TABLE 
limits access to the table to the current 
user only or allows other users only to 
read the table. Use the LOCK TABLE 
statement only when making major 
changes to a table in a multi-user 
environment and when simultaneous 
interaction with the table by another user 
would interfere. LOCK TABLE 
decreases the accessibility of the data- 
base, since it prevents other users from 
accessing the table. 


UNLOCK TABLE 
restores access to a previously LOCKed 
table. 


Ordinarily, when RDSQL locks a row, other attempts to access 
the data fail. If you wish to change this strategy, use the 
following statement: 
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SET LOCK MODE alters the locking strategy either to fail 
when a row is already locked or to wait 
for the lock to be released before 
proceeding. 


See the section "Locking" later in this chapter for a complete 
discussion of the kinds of locking ayailable and considerations 
for their use. 


Dynamic Management 


The pr"eceding discussion assumes that you embed explicit 
RDSQL statements in your INFORMIX-ESQUC program. That is 
the case for most applications where you are performing 
predetermined activities on your database. There are several 
ad\'anced applications, however. where you do not know the 
statement at compile time. These include the following: 


• 
Interactive programs, where the user enters a query from 
the keyboard at runtime. 


• 
Programs intended to work with different databases whose 
structure can vary. 


In situations like these, you must work with dynamically 
defined statements. The application of dynamically defined 
statements is more difficult than the use of non-dynamic 
statements. The following is a brief description of the dynamic 
management statements: 


i 
\. 


PREPARE 


EXECUTE 


takes a character string, interprets it as an 
RDSQL statement, and assigns it to a statement 
identifier. The· following dynamic management 
statements refer to the RDSQL statement 
through the statement identifier. 


runs the previously PREPAREd statement 
associated with the statement identifier. Use 
the EXECUTE statement for non-SELECT 
statements. 
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DESCRIBE 


DECLARE 


determines whether a previously PREPAHEd 
statement is a SELECT statement and. if so. 
gathers information about the storage require- 
ments for a single row. For statements other 
than SELECT, DESCRIBE returns only the 
statement type. 


declares a cursor for a PREPAREd SELECT 
statement. 


The RDSQL statement passed to PREPARE at runtime cannot 
refer directly to host variables, since the program has already 
been compiled. You should insert question marks (?) where 
you would have put the host variables. These question marks 
indicate the parameters of the statement. 


The following example illustrates the use of a dynamically 
defined non-SELECT statement. Dynamically defined 
SELECT statements will be described in more detail in 
Chapter 2 in association with the sqlda structure. 


$ 


$ 


char 
char 
long 
long 


statef128~; 
num~ 12J; 
- 
at 0 I () ; 
p_num; 


/. 
rea d 
s tat eme n t 
from 
t e r min a I 
• / 
get I ine(state, 
128); 


$ 
prepare stateid 
from $state; 
fore;;) 


prj n t f ("E n t e r 
c u s tome r 
numb e r: 
"); 
get I ine(num, 
12); 
p_num = atol(num); 
if 
(p_num = 
0) 
break; 
$ 
execute stateid 
using 
$p_num; 
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In this program fragment. an RDSQL statement is read from the 
terminal and placed into the character array state. It is 
presumed that the statement contains a single unknown value 
of type INTEGER. For example. 


delete 
from customer where customer 
num 
= 
? 


The program PREPAREs the statement and calls it stateid. 
The next part of the program is an infinite loop that requests 
personnel numbers and EXECUTEs the statement. substi- 
tuting the value in the host variable p_Dum for the question 
mark in the statement. The loop terminates when you enter a 
\·alue of zero for the personnel number. 


Locking 


I:\"FOR:\HX-ESQUC uses locking to prevent different users from 
executing conflicting operations on the same data. \Vithout 
locking. for example. two users may be allowed to update the 
same row at the same time. In this situation. the computer 
memory contains two different versions of the rows (the one 
being updated by user A and the one being updated by user B). 
\Vithout some method of concurrency control. the user whose 
row is the last one actually written to the file "wins" and 
overwrites the other user's changes. 


I:\"FOR:\HX-ESQLlC pf(wides two levels of locking to prevent such 
an occurrence: 


• 
Row-level or record-level locking 
• 
Table-level or file-level locking 


RDSQL performs row-level locking implicitly. The locking 
strategy may differ slightly. depending upon whether or not the 
database uses transaction management. Data definition state- 
ments. such as ALTER TABLE. CREATE INDEX. and so on. 
use implied table-level locking. You can explicitly specify 
table-level locking. The following sections describe each level 
of locking and the methods for employing it. 
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\ 
Row-Level Locking 


Ordinarily, RDSQL locks a row when you execute an UPDATE 
statement, or when you execute a FETCH statement and the 
cursor is DECLAREd with a FOR UPDATE clause. If the 
UPDATE statement affects only one row, RDSQL releases the 
lock immediately after performing the update. This prevents 
two programs from attempting to update the same record at 
the same time. One program receives the lock and can proceed 
with the update. The other program either fails in its attempt 
or waits for that program to release the lock. (See the section 
"Wait for Locked Row" later in this chapter.) 


If the UPDATE statement affects more than one row, RDSQL 
uses the same row-locking strategy. As soon as it completes an 
update, it releases the lock, then locks and updates the next 
record. When the UPDATE finishes, all records are unlocked. 


If you want more control over the update of multiple records, 
you can DECLARE a cursor FOR UPDATE. The WHERE 
clause of the SELECT statement specifies the rows that you 
want to update. After you OPEN the cursor and FETCH a 
record, that record remains locked until you either CLOSE the 
cursor or FETCH the next record. 


Row-Level Locking in Transactions 


If your database uses transaction management, rows that you 
INSERT, UPDATE or DELETE within a transaction remain 
locked until the end of the transaction. The end of a transac- 
tion is either a COMMIT WORK, where all modifications are 
made to the database or a ROLLBACK WORK, where none of 
the modifications are made. 


If you DECLARE a cursor for UPDATE, the fetch statement 
locks the row exclusively. If your application updates this 
record with the statement UPDATE WHERE CURRENT OF, 
this lock is held until the COMMIT WORK or ROLLBACK 
WORK statement is encountered. If the row is not updated, 
however, then the lock is released upon the next fetch. 
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Table-Level Locking 


You can use table-level locking to lock an entire table and 
prevent others from altering or seeing rows in that table. 


You may want to use this form of locking during batch opera- 
tions that affect every row in a table, for example. If the 
operations must be completed as a single transaction, it may be 
more efficient to lock the entire table before the transaction 
begins. Normally, under transactions, INFORMIX-ESQL/C locks 
each row as it is UPDATEd, DELETEd, or INSERTed. If you 
lock the entire table, however, INFORMIX-ESQL/C does not use 
row-level locking because it is unnecessary. As a result, you are 
not likely to reach the limits that your operating system may 
place on the number of rows that can be locked at anyone 
time. 


RDSQL performs table-level locking automatically as part of the 
following statements: ALTER TABLE, DROP TABLE, 
CREATE INDEX, ALTER INDEX, and DROP INDEX. 


INFORMIX-ESQLlC locks a table when you execute an RDSQL 
LOCK TABLE statement. The syntax for this statement is 


LOCK TABLE table-name IN ISHARE I EXCLUSIVE: MODE 


where table-name is the name of the table to be locked. 


If you lock the table IN SHARE MODE, other users are able to 
SELECT data from the table, but they are not able to 
INSERT, DELETE, or UPDATE rows in the table. If you 
lock the table IN EXCLUSIVE MODE, other users are not 
able to access the table at all until you execute an UNLOCK 
TABLE statement. 


Because locking an entire table prevents others from adding or 
altering data in the table, use this feature sparingly. Lock the 
entire table only when row-level locking (as described in the 
previous section) will not suffice. 
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Wait for Locked Row 


If another user locks a row in a table at the row level and you 
attempt to alter or delete that row (or examine it with 
SELECT statement FOR UPDATE), RDSQL returns an error 
stating that the row is locked. If you prefer that RDSQL wait on 
any locked row until the competing process unlocks it, you can 
execute the SET LOCK MODE TO WAIT statement. From 
then on, your request waits until RDSQL unlocks the requested 
row, and you do not receive an error message. If for some rea- 
son the competing process fails without unlocking the row, your 
process deadlocks. Consequently, use the SET LOCK MODE 
statement with caution. 


If another user locks a table in EXCLUSIVE MODE and you 
attempt to alter, to delete, or even to read a row in the table, 
RDSQL returns an error code. The wait-far-lock feature applies 
only on multi-user systems that support record-level locking. 
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User Status and Privileges 


When you create a database. you are automatically the 
Database Administrator (DBA) of that database and are the 
only one who has access to it. Another user cannot have access 
to a database until you grant the CONNECT privilege to that 
person. Another user cannot create or drop tables and indexes 
unless granted the RESOURCE privilege. Only the Database 
Administrator (you, initially) can grant these privileges. You 
can also grant the DBA privilege to another user. The DBA 
privilege extends all the powers of the Database Administrator 
to the grantee, including the ability to alter the system tables; 
to drop. start, and roll forward the database; and to grant 
CONNECT, RESOURCE, and DBA privileges to others. 


If you have the RESOURCE privilege. you have the 
CONNECT privilege by default. With the DBA privilege, you 
have both the RESOURCE and CONNECT privileges.. You 
can only revoke the privilege of a DBA grantee: you cannot 
revoke your own DBA privilege. If you as the creator of a 
database grant DBA privileges to another user, that user can 
revoke the DBA privilege from you, the database creator. This 
last property permits the transfer of authority from the maker 
of the database application to the person who has responsibility 
for maintaining the database. 


RDSQL allows the CONNECT and RESOURCE privileges to be 
granted to the PUBLIC in addition to specifically named users. 


In addition to these database-level privileges, there are a 
collection of table-level privileges that the owner of a table can 
grant. These permit the grantee access to specific columns for 
the purpose of executing SELECT or UPDATE statements, or 
give the grantee authority to insert new rows, to delete old 
rows, to create indexes, and to alter the structure of the table. 


Several of the RDSQL statements (ALTER TABLE, DROP 
INDEX, DROP TABLE, DROP VIEW, GRANT, RENAME 
COLUMN, RENAME TABLE, REVOKE) can be executed 
only by the DBA or by the owner of the table or index specified 
in the statement. 
(You can give others the privilege of 
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executing the ALTER TABLE, GRANT. and REVOKE 
statements with certain restrictions.) The owner of a table is 
the person (login name) who executed the CREATE TABLE 
statement. The owner of an index is the one who executed the 
CREATE INDEX statement. Execution occurs when the com- 
piled INFORMIX-ESQLlC program containing the CREATE state- 
ments is run, not when the INFORMIX-ESQL/C program is 
compiled. 


For single-user PC-DOS systems. since all tables and indexes 
created by a user are owned by pcuser, the previous 
discussion is irrelevant. 


Indexing Strategy 


There are two major purposes for creating an index on columns 
of a database table: to speed sorting of rows and to optimize 
the performance of queries. When your application writes 
reports involving complex queries through a large database, 
significant time savings can result from indexing. The draw- 
back to having an index is that indexes slow down the process 
of inserting new data into the database. When you update a 
table, its indexes may also be modified. This is not a problem 
when you are adding information interactively, a row at a time, 
but can become time-consuming when it is necessary to insert a 
large number of rows from one table into another. 


The solution to this potential conflict between needs is to take 
a pragmatic approach to indexing. One of the advantages of a 
relational database built upon C-ISAM is that you do not have to 
decide issues such as which columns to index at the time that 
you create your tables. You should write your applications to 
create indexes when you need them and to drop them when 
they get in the way. It takes time to create an index on a table 
already containing data, so create only those indexes that 
optimize the queries you make. For example, you may be able 
to schedule creating your indexes in anticipation of batch 
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report writing during the night and drop them the next 
morning before there are huge data-entry needs. 


The following suggestions are hints for effective indexing. 
Although the last two refer to a single query_ they apply when 
you anticipate making a number of queries with the same 
qualities. 


• 
Do not create indexes for small tables with fewer than 200 
rows. The speed you gain from using an index does not 
overcome the time required to open and search the index 
file on small tables. 


• 
Do not create indexes on a column that has only a few pos- 
sible values. Such columns are those that contain data like 
sex, marital status, yes/no responses. or zip codes in a small 
city. Performance of queries using these columns is not 
likely to improve and performance of inserts. deletes, and 
updates is likely to be slower. 


If you have a frequent need to have data sorted on columns 
with a small range of possible values. create a temporary 
table of the sorted data. Another approach is to redesign 
the database \"'ith separate tables for each alternative value. 


• 
If the WHERE clause of a SELECT statement imposes a 
condition on a single column. put an index on that column. 
If there are conditions placed on severai columns, make a 
composite index on all the affected columns. For the 
SELECT statement 


select 
• 
from 
items where order 
num > 
1015 


put an index on order_num. For the statement 


select 
• 
from 
items 
where order_num = 1015 
and total_price> 
1000.00 


create a composite index on both order_num and 
total-cprice. 
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• 
If the \VHERE clause of a SELECT statement has a join 
condition between a single column in one table and a single 
column in another table, create an index on the column in 
the table with the larger number of rows. If several columns 
of one table have join conditions with several columns in 
another table, create a composite index on the affected 
columns of the table with the larger number of rows. For 
the SELECT statement 


select 
• 
from 
items, 
stock 
where 
items.stock_num = 
stock.stoc~num 


place an index on stock_num in the items table, since it 
has many more rows than the stock table. Execute the 
UPDATE STATISTICS statement before the SELECT 
statement so that RDSQL knows the current size of the 
tables. 


For the statement 


select 
• 
from 
items, 
stock 
where 
items.stock_num = stock.stock_num 
and 
items.manu code'= stock.manu_code 


put a composite index on stock_ num and manu_code in 
the items table. 


Auto-Indexing 


If you execute a SELECT statement that includes a join 
between two tables and there are no indexes on the joined 
columns, RDSQL creates a temporary index on the table with the 
larger number of rows before performing the join. The index 
disappears when the query finishes. This enhancement is 
transparent to the user except for a dramatic improvement in 
the speed of unindexed queries. 
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Clustered Indexes 


Since both UNIX and DOS extracts information from the disk 
in blocks, the more rows that are physically on the same block 
and are already in the order of an index, the faster sequential 
retrieval using an index will proceed. Ordinarily, no relation- 
ship need exist between the physical order of the data in the 
.dat file and the order of an index. You can, at least tem- 
porarily, cause the physical order in the table to be the same as 
the order in an index through clustering. 


RDSQL orders, or clusters, the physical data in a table when you 
create a new index by executing the CREATE CLUSTER 
INDEX statement or when you execute the ALTER INDEX 
statement to cluster for an existing index. Since users who 
have access to the table can add additional rows or update the 
information in existing rows, a table that you cluster according 
to an index does not stay that way. Over time, you can expect 
the benefit of an earlier clustering to disappear and you may 
want to cluster the table again using an ALTER INDEX TO 
CLUSTER statement. 
. 


Since a table can have only one physical order, you can have 
only one clustered index on a table at any given time. You can 
change the physical order to reflect a different index by execut- 
ing two ALTER INDEX statements: 


1. Execute an ALTER INDEX TO NOT CLUSTER state- 
ment to release the cluster attribute from the first index. 


2. Execute an ALTER INDEX TO CLUSTER statement to 
attach the cluster attribute to the second index. 


You cannot execute the ALTER INDEX or CREATE INDEX 
statements on a view. 
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NULL Values 


The basic purpose of introducing NULL values in a database is 
to indicate when no value has been assigned to a particular 
column in a particular row of a table. Your reasons for not 
having assigned a value could either include not knowing the 
correct value or that no value yet exists. The NULL may also 
indicate that no value is appropriate for a given column 
because of the values that were entered into other columns. 


For example, consider entering data for a bank customer who is 
requesting a loan. If the customer, Mr. Farthing. is not 
employed, the employer column in the client table has no 
entry for this customer. This CHAR column has the value 
NULL. The hire_date column is meaningless if Mr. Farthing 
is not employed. There is no appropriate date to enter; the 
value is NULL. 


Default Values 


In RDSQL, the default value for a column is NULL. RDSQL 
makes. a distinction between zero and NULL for numeric 
values and between blanks and NULL for character values. 


By definition, type SERIAL columns can never contain the 
NULL value. Columns of type SERIAL always contain 
integers greater than or equal to one. 


You can insist that a column of any type not have NULL 
values by using the NOT NULL clause in the CREATE 
TABLE statement. RDSQL prevents a NULL from being 
entered into any column that is declared NOT NULL. 


You c~nnot, however, use a NOT NULL clause in an ALTER 
TABLE statement when you add a new column. The reason is 
that RDSQL enters a NULL value into that column for all rows 
that already exist. 


1-37 


A column for which you create a unique index can have, at 
most, one NULL value. 


Note for users of the 
Version 1.10 implementation ofRDsQL: 


In Version 1.10 RDSQL, when no value is provided for a column 
entry in a row of a table, RDSQL enters a blank for type CHAR 
columns, zeroes for numeric columns, and a very large negative 
value for type DATE columns. Since zero could well be an 
acceptable value for a numeric column (for example, the value 
for a type MONEY column), there is no way to distinguish an 
unknown value from zero. 


To incorporate your existing Version 1.10 database into 
INFORMIX-ESQLlC programs, you must execute the dbupdate 
utility described in Appendix H. (Appendix H also describes 
how you can avoid using NULL values.) 


The NULL in Expressions 


If any value that participates in an arithmetic expression is 
NULL, the value of the entire expression is NULL. For 
example, consider the following query: 


select 
order_num. 
ship_charge/ship_Vveight 
from orders 
where 
order_num = 1023 


When ship_charge is NULL because the order with number 
1023 is new and the shipping charge has not yet been deter- 
mined, the value returned for ship_charge/ship_weight is 
also NULL. 


The situation is different when you use one of the aggregate 
functions (see Chapter 3 for a description of the aggregate 
functions). COUNT(*) counts all rows, even if the value of 
every column in the row is NULL. COUNT(DISTINCT 
column-name), AVG, SUM, MAX, and MIN ignore rows with 
NULL values for the column in their argument and return the 
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appropriate value based on the rest of the rows. However, if a 
column contains only NULL values, then COUNT(DISTINCT 
column-name} returns zero, and the other four aggregate 
functions return NULL for that column. 


The NULL in Boolean Expressions 


In order to incorporate NULL values into Boolean expressions, 
it is necessary to enlarge the number of truth values from 
simply true and false to include unknown. If one of the expres- 
sions of a Boolean expression is NULL, the truth value of the 
Boolean expression is unknown. For example, the Boolean 
expression, 


ship_charge/ship_weight 
< 5.0 


has the truth value unknown for the order in the previous 
example. 


If you combine Boolean expressions using the operators AND, 
OR, and NOT, the following tables give the resulting truth 
value (where T corresponds to true, F to false, and? to 
unknown). 


AND 
T 
F 
? 
OR 
T 
F 
? 
NOT 


...... - _ ............ - 
......... - ............... 
T 
T 
F 
? 
T 
T 
T 
T 
T 
F 
F 
F 
F 
F 
F 
T 
F 
? 
F 
T 
? 
? 
F 
? 
? 
T 
? 
? 
? 
? 
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The NULL in WHERE Clauses 


If the Boolean expression in a WHERE clause evaluates to 
unknown for a particular row, RDSQL treats the search condition 
as not satisfied and does not select or modify that row. 


Consider the following clause: 


where ship__charge/ship__weight < 5 
and order__num = 1023 


The row where order_nurn = 1023 is the row where 
ship_charge is NULL. Since ship_charge is NULL, 
ship_charge/ship_weight is also NULL, and the truth 
value of ship_charge/ship_weight < 5 is unknown. Since 
order_nurn = 1023 is true, the preceding AND truth table 
states that the truth value of the entire search condition is 
unknown. Consequently, that row is not chosen. If the search 
condition had used an OR in place of the AND, the search 
condition would be true. 


You can select (or reject) rows containing NULL values with a 
new type of search condition: 


column IS [NOT] NULL 


You must use the keyword IS. It is not permitted to write the 
condition as follows: 


column = NULL 
column != NULL 
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(Incorrect) 
(Incorrect) 


If you perform a join between two tables using the WHERE 
clause, 


where column1 = column2 


RDSQL does not select the rows where either column1 or 
column2 is NULL. In particular, no row is returned if both 
column1 and column2 are NULL. This is merely a special 
case of the more general rule that Boolean expressions 
containing NULL values have an unknown truth value. 


Similarly, if a subquery returns a single NULL value, the 
search condition evaluates to unknown. 


The NULL in ORDER BY Clauses 


For the purpose of sorting rows using the ORDER BY clause, 
the NULL value is treated as being less than a non-NULL 
value. When the ordering is ASe, the NULL values come first; 
when the ordering is DESe, the NULL values come last. 


The NULL in GROUP BY Clauses 


RDSQL treats each row containing a NULL value in the column 
being GROUPed BY as if it is in a separate group. This is con- 
sistent with the fact that each NULL value is really unknown. 
There is no reason to assume that all NULL values are the 
same. 
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The NULL Keyword in INSERT 
and UPDA TE Statements 


When you execute the INSERT statement, RDSQL inserts the 
NULL value into all columns for which you do not provide a 
value and for all columns not listed explicitly. Since the 
ualue-list of the INSERT statement must be the same length 
as the column-list, you can use the keyword NULL to indicate 
that a column in column-list should be assigned a NULL value. 


insert 
into orders 
(order_num, 
order_date, 
customer_num) 
values 
(0, 
null, 
123) 


All other columns in the orders table are filled with NULL 
values. Similarly, you can use the NULL keyword to modify a 
column value when using the UPDATE statement. For a 
customer whose previous address required two address lines. 
but now requires only one, you would use the following entry: 


update customer 
set 
address1 = "123 New Street", 
address2 = nu I I , 
city = "Palo Alto", 
zipcode = "94303" 
where customer 
num = 134 
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Views 


Views are constructs on a database that allow you to do the 
following tasks: 


• 
Provide different users with different windows (called 
"views") on the data in the database. A single view may 
involve columns from different tables or may show values 
that are functions of the values from the columns. A view 
has a name and looks to a user as if it were a table. The 
user can query a view, for example, using the same syntax 
as though the view were a table in the database. 


• 
Limit access to sensitive data by allowing users to see only 
aggregate information. With the GRANT and REVOKE 
statements, you can prevent a user from seeing any salary 
data in a personnel table. With a view, you can allow the 
user to see average salaries in various groups, but still 
protect the individual salary data. 


• 
Permit users to update, insert, and delete data in the 
database as though the data were organized as it appears in 
a view. You can also examine the changes made in a real 
table of the database through a view. 


Views are therefore dynamic windows into the database and are 
not static snapshots. They differ in this respect from a tem- 
porary table created by the INTO TEMP clause of a SELECT 
statement or the CREATE TEMP TABLE statement. Such 
temporary tables show you only the state of the database when 
the temporary table was created. 


Although views appear to be tables in the database, there are 
several important ways in which they differ. You cannot use a 
view in place of a table in a form specification file. You cannot 
create an index on a view. There are conditions under which 
you cannot update or modify the data perceived through a 
view. An obvious case occurs when the "column" seen in a 
view is really an expression generated from actual database 
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tables. Generally speaking. there is no way to determine the 
appropriate change in the underlying columns involved in such 
an expression if you want to change the value of the "column." 


The next sections describe how to create and delete views, how 
to query the database through views, how to modify the data- 
base through a vie\v, and how to set up permissions for a view. 


Creating and Deleting Views 


You must use the CREATE VIEW statement to create a view. 
As described in Chapter 3, a view is determined by a SELECT 
statement that returns the "table" that defines the view. You 
cannot use the UNION operator (see Chapter 3 for the 
definition of the UNION operator) in the definition of a view. 
The SELECT statement is stored in the sysviews system 
catalog. When you subsequentl~; make reference to a view in 
another statement, RDSQL performs the defining SELECT 
statement in executing the new statement. 


You can use the same column names as in the underlying table 
for the view or you can assign new names. When a column in a 
view is the evaluation of an expression or is not unique 
(because, for example, you have included all the columns of a 
join, including the columns that define the join), you must 
supply new names. These column names are stored in 
syscolumns along with the column names of regular tables. 


You can delete a view by executing the DROP VIEW 
statement. When you drop a view, you also drop all views that 
were defined in terms of that view. 
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Querying Through Views 


You can make queries involving vie\';s exactly as though they 
were tables in the database. If possible. RDSQL first .combines 
the view-defining SELECT st~tement with the query to create 
a new SELECT statement and then executes the new state- 
ment. Otherwise, it creates the view as a temporary table and 
applies the query to the table. RDSQL may detect errors during 
either of these phases and return a negative value in the struc- 
ture element sqlca.sqlcode. (See Chapter 2 for a discussion of 
the sqlca structure.) 


Modifying Through Views 


As in querying through views, you can use the INSERT, 
UPDATE, and DELETE statements with views. RDSQL com- 
bines the view-defining SELECT statement with the view- 
referring statement and then executes it. The following 
restrictions apply to modifying tables through a view: 


• 
You cannot modify the database through a view if the view 
definition involves joins, the GROUP BY clause. the 
DISTINCT keyword, or an aggregate function. If any of 
these features is present in the view definition. the creator 
of the view cannot execute INSERT, DELETE. or 
UPDATE statements on the view. You can, however. define 
a view using a subquery that refers to another table and can 
often circumvent the restriction on joins (see the section 
"Data Constraints Using Views" later in this chapter). 


• 
A vie\v column can be UPDATEd only if it is derived 
directly from a table of the database and not as a result of 
an expression. Expression-derived columns are called "vir- 
tual" columns. You cannot INSERT rows through a view 
that contains virtual columns, although you can DELETE a 
row that contains a virtual column. 
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• 
You cannot execute the ALTER TABLE. CREATE 
INDEX. or UPDATE STATISTICS statements on a viev.', 
You do receiw the benefit of existing indexes on the 
underlying tables. 


You can use an INSERT statement on a view that shows only 
a portion of an underlying table. When you do so, the unmen- 


. tioned columns of the underlying table receive NULL values, 
If one of the unmentioned columns does not permit NULL 
values. RDSQL doesnot permit you to INSERT to the view. 


If you drop a column of an underlying table of a view that you 
ha\'e defined in terms of that column, RDSQL issues an error if 
you subsequently make reference (other than DROP VIEW) to 
the view. 


Unless you create the view with a \VITH CHECK OPTION 
clause, it is possible to INSERT or UPDATE data into a data- 
base through a view that does not satisfy the limitations on the 
view. A row INSERTed or UPDATEd in this manner is no 
longer accessible through the view. For example, a view could 
be created that allows the user access only to customers from 
Palo Alto. If, when using the view, the user creates a new row 
with a customer from Menlo Park, the user cannot select the 
row through the view. If the city column on an existing row is 
UPDATEd to Menlo Park, the row disappears from the view. 
The WITH CHECK OPTION clause on the CREATE VIEW 
statement causes RDSQL to reject an UPDkTE or INSERT that 
violates the restrictions of the view. 


You must be careful when you UPDATE a table through a view 
that may contain duplicate rows. Duplicate rows can occur in a 
view even if the underlying table has unique rows. If a view is 
defined on the items table and contains only the columns 
order_num and total_price, the view contains duplicate 
rows if two items from the same order have the same total 
price. If you put the cursor on one of the rows where 
total_price = $1234.56 and update the total_price to 
$1250.00 through the view, you have no way of knowing which 
item you have increased. 
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Privileges with Views 


When you create a view. you receive the same privileges that 
you had on the underlying tables. If you have these pri\'ileges 
with the GRANT OPTION (see Chapter 3). you can grant 
privileges on your view to other users, 


If the view is built on more than one table, you can have only 
the SELECT privilege since multi-table \'iews do not permit 
you to INSERT, DELETE, or UPDATE. You must have the 
SELECT privilege on all the columns from which a multi-table 
view is derived to have the SELECT privilege on the entire 
view. If, as a result of these restrictions, you have no privileges 
on a view, the CREATE VIE\V statement returns an error 
code. 


Data Constraints U6ing Views 


The purpose of data constraints is to ensure that all data 
entered into the database satisfies preassigned limitations. It is 
often desirable to define allowed value ranges dynamically. 
based on the values in other columns or even in other tables. 
The existence of views and, specifically. the WITH CHECK 
OPTION clause permits the DBA to control the entry of data 
into th~ database. This is most easily demonstrated with an 
example taken from the stores database. 


Suppose you want to ensure that no item 


• 
Has a value of more than $20.000 
• 
Is for stock that does not exist 
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The first step is to create the following view: 


create view safe 
items as 
s e Iect· 
from 
items 
where totalJrice < 20000 and 
exists (select 
stock_num, 
manu_code 
from stock 
where stock.stock 
num 
items. stock 
num 
and stock.manu code 
items.manu_code) 
wi th 
check opt ion 


If you do all data entry and data modification through the 
safe_items view. RDSQL rejects all data that does not meet the 
requirements of the WHERE clause. Because of the dynamic 
nature of \'iews, the view will only contain rows corresponding 
to current stock items if you change the stock table by adding 
rows corresponding to new stock items or by deleting old on.es. 


By extending the WHERE clause, this example can be 
expanded to cover very general data-constraint needs. 
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Outer Joins 


An outer join between two tables treats the two tables unsym- 
metrically. One of the tables is dominant (often referred to as 
"preserved"), and the other table is subservienL If the subser- 
vient table has no rows satisfying the join condition, the outer 
join attaches a row of NULL values to the row of the dominant 
table before projecting the desired columns. To illustrate, let a 
be a column from tab! and b a column in tab2. Further. let 
the values in the two tables be as shown in the following 
display: 


tabl.a 
tab2.b 


2 
4 
3 
2 
5 
6 
5 


RDSQL syntax requires that the subservient table in an outer 
join be preceded by the keyword OUTER in the FROM clause. 
The following SELECT statement contains an outer join 
between tab! (the dominant table) and tab2 (the subservient 
table): 


select 
a, 
b 
from tab1, 
outer 
tab2 
where 
a = b 


The resulting table has the following two columns: 


a 


2 
3 
5 


b 


2 


5 


Every value for a is present, and only those values of b that 
match those in a are present. When there is no value in 
column b that satisfies the join condition, a NULL value 
(shown here as -) is substituted. 
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A WHERE clause is required in the case of outer joins and 
must set acondition between the two tables. 


See Chapter3 and Appendix J for more information about 
outer joins. 


Table Access by Row ID 


The keyword RO\VID can be used in RDSQL statements to refer 
to the C-ISA:\f record number associated with a row in a data- 
base table. ROWID can be thought of as a hidden column in 
every table. When you refer to table.*. the implied list of 
columns does not include ROWID. On the other hand, you can 
use the syntax 


5 e lee trow i d, 
• 
from table 


to get the ROWID value for each row. You can also determine 
the ROWID of the last row that RDSQL dealt with by examining 
the sqlca structure (see Chapter 2). 


ROWID can also be used in \\'HERE clauses to select rows 
based on their C-ISA:\f record number. This feature is useful 
when there is no other unique column in a table. 


If a row is deleted from the table. its ROWID may be assigned 
to a ne\v row. You should not attribute chronological or other 
significance to the sequential values of ROWID. 
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TODAY and USER Functions 


RDSQL provides functions to allow you to include the date and 
the user's name in a statement. TODAY always returns the 
system date. USER returns a string containing the current 
user's name. On UNIX systems, this is the login name; on 
DOS systems this is either the machine name or the constant 
pcuser. 


You can use these functions wherever you use a constant. For 
example, if you want to retrieve the rows you inserted into a 
table, you must first define a column to contain the USER 
name. When you insert into the table, use the USER function 
as follows: 


$ 
ins e r tin totable val u e s (..., use r , . . . ) ; 


You can then retrieve the rows you entered with a select state- 
ment, as follows: 


select 
• 
from table 
where user_col = user 


(See the section "Cursor Management" earlier in this chapter 
for a discussion on using the SELECT statement to return 
multiple rows.) 


You can use the TODAY function in the same way. To insert 
the system date into a table, use the following statement: 


$ 
ins e r tin totable val u e s (..., t 0 day, . . . ) ; 


To retrieve all rows with today's date from a table, the follow- 
ing statement can be used. 


s e I e ct· 
from table 
whe r e date_col = 
today 
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Chapter Overview 


This chapter describes the structure of an INFORMIX-ESQL/C 
program and introduces several basic concepts. You will learn 


• 
How RDSQL statements are embedded in C programs 
• 
How C variables are identified with database constructs 
• 
How to detect errors 
• 
How to keep track of queries that return multiple rows 
• 
How to use dynamically defined RDSQL statements 
• 
How to preprocess and then compile your C program 


C programs that use INFORMIX-ESQLlC statements generally 
include the following elements: 


• 
Header files 
• 
Include files 
• 
Host variables 
• 
Indicator variables 
• 
INFORMIX-ESQLlC statements 
• 
Errorhandling 


Your program may also include dynamically defined 
statements. This chapter describes each of these topics. 
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Header Files 


The C program that contains INFORMIX-ESQL/C statements 
includes the following header files: 


sqlca.h 
contains the structure in which error messages 
are stored. 


sqlda.h 
contains the structures that contain value 
pointers and descriptions of dynamically 
defined variables. 


sqIstmtype.h 
contains integer constants corresponding to 
RDSQL statements. 


sqltypes.h 
contains the definitions of strings correspond- 
ing to C language and RDSQL data types. 


The syntax for including these files is as follows: 


$include 
$include 
$include 
$include 


sqlca; 
sqlda; 
sqlstmtype; 
sqltypes; 


You need not include sqlda.h, sqIstmtype.h, or sqltypes.h 
unless your program makes reference to the structures or the 
definitions included in them. Always include sqlca.h to check 
the success or failure of your INFORMIX·ESQLlC statements. 


You can read more about sqlca.h and sqlda.h later in this 
chapter. You will find sqIstmtype.h mentioned in association 
with the DESCRIBE statement in Chapter 3, "RDSQL State- 
ments." sqltypes.h is discussed in Chapter 4, "RDSQL Data 
Types." These files are reproduced in Appendix A. 
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Include Files 


You can use the $include preprocessor statement to include 
other INFORMIX-ESQLlC files in your program in addition to 
header files. Use the following syntax: 


$include filename 


The INFORMIX·ESQLlC preprocessor reads filename into the 
current file at the position' of the include statement, processes 
it, and passes it on to the C compiler. The standard #include 
of C includes the file after the INFORMIX·ESQL/C preprocessor 
stage. You must use $include if filename contains RDSQL 
statements. 


Host Variables 


Host variables are normal C variables that you use in RDSQL 
statements. When you use a host variable in an RDSQL state- 
ment, prefix its name with a dollar sign ($). The host variable 
hostvar, for example, appears in an RDSQL statement a~ 
$hostvar. For compatibility with other implementations of 
SQL, you can use a colon (:) in place of the dollar sign. 
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Host variables are declared as ordinary C variables, except that 
the declaration must be preceded by a dollar sign ($): 


/* pointer 
to a character 
*/ 
$ 
char 
*hostvar; 


/* 
integer 
*/ 
$ 
i n t 
ho s tin t ; 


/* 
long 
integer 
*/ 
$ 
long 
host long; 


/* 
double 
*/ 
$ 
double hostdbl; 


/* character array 
*/ 
$ 
char 
hostarr[aO]; 


/* structure */ 
$ 
struct 
( 
int 
svar1; 
int 
svar2; 


) hostst ruct; 


Since host variables appear in RDSQL statements, they are 
associated with an RDSQL data type. In addition, a host vari- 
able must be declared as a C data type. The relationship 
between RDSQL data types and C data types is described in 
detail in Chapter 4. The example that follows summarizes the 
-relationship. 


RDSQL 


CHAR(n) 
SMALLINT 
INTEGER 
SERIAL 
SMALLFLOAT 
FLOAT 
DATE 
MONEY 
DECIMAL 
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C Language 


char array[n + 1] 
short int 
long int 
long int 
float 
double 
long int 
struct decimal or dec 
t 
struct decimal or dec= 
t 


If the host variable is not declared according to this example, 
RDSQL attempts data type conversion if the conversion is 
meaningful. See Chapter 4 for a discussion of data conversion. 


You can define as many host variables as you need (up to the 
limit set for the symbol table of your C compiler). You cannot 
use more than 50 host variables in a single RDSQL statement. 


The representation of NULL values depends on both the 
machine and the data type. Often the representation does not 
correspond to a legal value for the C data type and you should 
not attempt to perform arithmetic or other operations on a 
host variable that may have a NULL value. INFORMIX-ESQLlC 
provides two functions that enable you to test whether a host 
variable corresponds to a NULL value (risnull) and to set a 
host variable to a NULL value (rsetnull). See Chapter 5 for a 
description of the these functions. You must also define indica- 
tor variables for all host variables that correspond to database 
columns that allow NULL values. 


The INFORMIX-ESQL/C preprocessor issues a warning if you 
declare a host variable in one function and then redeclare it in 
another function. It considers a structure to be redeclared if 
any of its elements differ in name, type, or length from those 
declared earlier. The warning states that the preprocessor will 
use the second declaration from then on. This situation can 
happen with the declaration of an index i as int in one func- 
tion and as long in another. If each such variable is a local 
variable, you can ignore the warning. When you declare the 
variable as extern or as global to a file, however, subsequent 
redeclaration inside a function can cause subtle errors. 
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You can assure that the host variables declared within a 
function are local to that function by using the combined 
symbol pair $: and $: to open and close the function: 


$ 
extern 
int 
hostvar; 


func1() 
$: 
$ 
long hostvar; 


func2() 


$ 
declare 
~stock cursor 
for 
select 
stock_num 
into $hostvar 
from stock; 


The host variable hostvar declared in funcl has a scope only 
within that function. The variable hostvar used within func2 
is the one that is declared as extern. 


You can also use the combined symbol pair $: and $: to open 
and close blocks within a function. Host variables declared 
within such a block are local to that block. You can nest blocks 
up to 16 levels. The global level counts as level one. 
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Indicator Variables 


Since a NULL value is often not a definite value among other 
values. you must be able to find out if an INFORMIX-ESQLlC 
statement returns a NULL variable to a host variable. If a 
host variable corresponds to a database column that allows 
NULL values, you should define an indicator variable in 
association with a host variable. The associated host variable 
is called a main variable. When an INFORMIX-ESQLlC statement 
returns a NULL value to a host variable (through the INTO 
clause of a SELECT or a FETCH statement) and you have 
defined an indicator variable, the indicator variable has a nega- 
tive value. The actual value in the host variable may not be a 
meaningful C value. If you have not assigned an indicator vari- 
able to the host variable and INFORMIX-ESQL/C returns a NULL 
value, it is an error and RDSQL sets sqlca.sqlcode to a negative 
value (see the section "Error Handling and the sqlca Structure" 
later in this chapter). 


When a non-NULL RDSQL value is retrieved into a host 
variable character array, it may have to be truncated to fit. In 
this case, INFORMIX-ESQLlC sets the associated indicator variable 
equal to the size in bytes of the RDSQL variable before trunca- 
tion. The fact of truncation is signaled in the sqlca structure; 
the indicator variable tells you the extent of the truncation. If 
the returned value is neither NULL nor truncated, the 
indicator variable has the value zero. 


The indicator variable must be declared as a short integer. You 
must prefix a colon (:) before an indicator variable name and 
immediately after the main variable name when you reference 
the indicator variable in an RDSQL statement. (You can use a 
dollar sign ($) instead of a colon, but the colon makes the code 
easier to read.) If hostvarind is the indicator variable for the 
main variable hostvar, you represent the pair in an RDSQL 
statement as $hostvar:hostvarind. 
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Examples 


$ 
$ 
$ 
$ 


char 
char 
s h 0 r t 
s h 0 r t 


name 
16 
comp 
20 
name 
nd 
comp 
nd; 


$ 
select 
Iname, 
company 
into $name:nameind, 
$comp:compind 
from customer 
where customer_num = 105; 


If lname is defined in the customer table as having a length 
longer than 15 characters, nameind contains the actual length 
of the lname column. name contains the first 15 characters 
(the string name must be terminated with a null character). If 
the last name of the company representative with customer 
number = 1005 is shorter than 15 characters, only trailing 
blanks are truncated. 


If company has a NULL value for this same customer, 
compind has a negative value. The contents of character 
array comp cannot be predicted. 


As an alternative to using the NULL keyword in the INSERT 
statement, you can use a host variable with.a negative indicator 
variable. 
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Embedding RDSQL Statements in C Routines 


RDSQL statements are embedded in a C rout in€-' '\'it h tIw 
following 
s~'ntax: 


S 
NlJ .....·({!. s/a/I'mrll/: 


I:\,FOIDlIX-ESQIA' statements can include host \'ariables (and 


usuall~' indicator \'ariables as well) in an\ place a constant can 
be used. 
See the rules for indi\'idual statements in Chapter :1 


for any except ions. 


Error Handling and the sqlca Structure 


Proper database management requires that all logical ,;equences 
of st atement s t hat 
modif~' the dat abase cont inue 
su('('e,;sfull~' to 
completion. 
H. for example. you l~PDATE a customer account 


to show a reduction of ~1O() in the payable balance and. for 
some reason. the next step to lTPDATE the cash balance fails. 
your books will be out of balance. It is important to check that 


eYer~' RDSQL stat ement execut es as ~'ou ant icipat ed. 


I:\'FOR:\lIX-ESQLtC ret urns a result code int 0 the sqlca st rud ure 
after executing eyery RDSQL statement except DECLARE. Thi,; 
structure is defined in sqlca.h and is shown here. 
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struct sqlca_s : 
long sqlcode: 
char sqlerrm[72]: 
char sqlerrp[8]: 
long sqlerrd[6]: 
struct sqlcaw_s : 
char sqlwarnO: 
char sqlwarn1; 
char sqlwarn2: 
char sqlwarn3: 
char sqlwarn4: 
char sqlwarn5: 
char sqlwarn6: 
char sqlwarn'i: 
: sqlwarn: 
: sqlca: 


Explanation 


sqlcode 
indicates the result of executing an IXFOR:\IIX-ESQUC 
statement. 


It is set to zero for a successful execution of most 
statements and to SQLNOTFOUND (defined as 100 
in sqlca.h) for a successfully executed query that 
returns zero rows or for a FETCH that seeks beyond 
the end of an active set. 


sqlcode is negative for an unsuccessful execution. 
See the special chapter, "Error Messages." following 
the appendixes for the error codes and their 
meaning. 


sqlerrm 
is not used at present. 


sqlerrp 
is not used at present. 


sqlerrd 
is an array of six long integers: 
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sqlerrd[O] i,; not used at pre,;ent. 


sqlerrd[l] is a SEHIAL \'aluE-' rE-'turllt'c1 or ISA\! 


error codE-', 


sqlerrd[2] is the number of row,; proce,;,;E-'c1. 


sqlerrd[3] is not used at prbent. 


sqlerrd[4] is the offset of error intI) t1w HDS(~1. 


statement. 


sqlerrd[5] is the HO\\'ID of last rm\". 


sqlwarn 
is a structure containing eight character,; that signal 
\'arious warning condit ion,; (as opposed to errors) 
following the execution of an HDSQI. statement. 
'1'lw 
characters are blank if no prohlems were detected. 


sqlwarnO 
is set to \\1 if one or more of the other 
warning character,; has lWE-'n set to \\T, 
If sqlwarnO is blank. 
~'ou do not ha\'e 
to check tlw remaining warning 
characters. 


sqhvarn 1 
is set to \\1 if one or more data items 
\vas truncated to fit into a character 
host \"ariable. 
You can disc()\'er which 
item was truncated 
h~' examining the 
associat ed indicator \'a riables. 


sqlwarn2 
is set to W if an aggregate function 
(St TJ\1. AV(;. MAX. MIT\") encountered 
a Nt 1Ll. \'alue in its e\·a!uation. 


sqlwarn3 
is set to \\" when the numher of item,; in 
the select-list of a SELECT clausE' is not 
the same as the numher of host \"ari- 
abIes in the INTO clause. The numlwr 
of items returned 
h~' HDS(l!. ne\"er 


exceeds the number of host \·ariables. 
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sqlwarn4 is set to 'W by the DESCRIBE 
statement when an UPDATE or 
DELETE statement is PREPAREd 
without a WHERE clause. Without a 
WHERE clause, the UPDATE or 
DELETE applies to the entire table. By 
checking this variable, you can avoid 
unintended global changes to your table. 


sqlwarn5 is not used at present. 


sqlwarn6 is not used at present. 


sqlwarn7 is not used at present. 


By taking corrective action when sqlca.sqlcode is negative, 
you can recover from the failure of an intended modification of 
your database. By checking for sqlca.sqlcode = SQLNOT~ 
FOUND, you can write code to process the results of queries 
only when rows are returned. 
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Dynamic RDSQL Statements 
and the sqlda Structure 


Under the following three circumstances, the treatment of 
dynamically defined RDSQL statements is more complicated 
than described in Chapter 1 and requires you to use the sqlda 
structure: 


• 
In non-parameterized SELECT statements where you know 
neither the number nor the data types of the members of 
the select-list, nor the list of column names or expressions 
in the SELECT clause 


• 
In SELECT statements where you do not know the number 
or data type of the parameters in the WHERE clause 


• 
In Non-SELECT statements where you do not know the 
number or data type of the input parameters 


If you are not using statements of these kinds. you can skip the 
rest of this section. 


Before looking at the procedure you must follow for each of 
these statements, consider the sqlda structure. 


The sqlda Structure 


When all of its components are fully defined. the sqlda struc- 
ture points to the beginning of a sequence of sqlvar_struct 
structures that contain the necessary information for each 
variable in the set. 
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~I ruel sljh'ar 
~lrUel: 
shllrl 
slj!l~'pe: 


~hllrl sqllen: 
chBf *sqldata: 
short *sqlind: 
char *sqlname: 
char *sqlformat; 


~lru("1 ,.;qlda : 


short sqld: 
sl ruel ,.;qh-ar 
st rul't 
*sql\"ar: 


,.,. 


Explanation 


sqItype 
is a short integer corresponding to the data type 
being transferred. The integer correspondences are 
defined in sqItypes.h. 


sqJlen 
is a short integer that gives the size in bytes of 
CHAR type data. 


sqldata 
is a pointer to the data. 


sqlind 
is a pointer to a short integer indicator \·ariable. 


sqlname 
is a pointer to a character array containing the 
column name or display label being transferred. 


sq]format is a pointer to a character array and is reserwd for 


future lise. 


sqld 
is a short integer that is the number of \'alues 
ret urned for each row of t he 
qller~·. 
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Non-Parameterized SELECT Statements 


In the SELECT statements described earlier. the values 
returned from the query are placed into host variables that are 
listed in an INTO clause. When you create a SELECT state- 
ment interactively after you compile your program, you cannot 
use an INTO clause since the host variables are not directly 
available. You must use an sqlda structure. 


There are several steps in this process: 


1. Declare a pointer to an sqlda structure (name it udesc). 


2. PREPARE the SELECT statement and give it a statement 
identifier (let it be u_query). 


3. Execute the statement 


$ 
describe 
u_query 
into 
udesc; 


This statement causes udesc->sqlvar to point to a 
sequence of partially filled sqlvar_struct structures. 
(udesc->sqld gives the number of sqlvar_struct struc- 
tures.) The components of each sqlvar_struct structure 
filled by the DESCRIBE statement for each item of the 
select-list are sqItype. sqIlen (for CHAR type datal. and 
sqlname" 


4. 
Allocate memory for the expected values and assign pointers 
to them (sqldata and. optionFl1ly. sqlind) in each 
sqlvar_struct structure. This im"oh"es your using a func- 
tion like maIlocO and assigning proper \\"orcl boundaries. 
depending upon the data type and. in the case of CHAR 
variables. the length of the variable. 


5. 
Declare a cursor for the PREPAREd statement ident ifier 
(name the cursor u 
cursor). 
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6. 
Execute the following statement: 


$ 
fetch 
u_cursor 
using descriptor 
u_desc; 


This statement assigns values to the variables pointed to by 
the various sqldata pointers. 


,. Optionally. repeat the FETCH statement. 


All dynamically defined SELECT statements must have a 
declared cursor. 


To illustrate the process. consider the following program 
fragment in which all error checking has been suppressed. 
This example assumes that a SELECT statement has been 
assembled at runtime and is stored in the string <l..-string. 
As an illustration. use the following statement: 


select 
order_num. 
order_date 
from orders 
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$include 
sqlca; 
$include 
sqlda; 


/* 
declare pointer 
to structure 
that 
a p p 0 r t ion s 
the 
d a t a 
from 
e a c h 
r ow 
* / 
struct 
sqlda 
*Ldesc; 


/* 
declare 
host 
variable 
to 
hold 
s tat erne n t 
s t r i n g 
* / 
$ 
char 
Lstring[128]; 


/. 
make 
stores 
the 
current 
database ./ 
$ 
database stores; 


/. 
At 
this 
point 
the 
SELECT statement 
is 
assigned 
to Lstring 
./ 


/. 
prepare 
the 
SELECT 
statement 
./ 
$ 
pre par eLi d 
from 
$ L 
s t r i n g ; 


/. 
identify 
the select-list ./ 
$ 
describe Lid 
into Ldesc; 


/. 
this 
section 
of 
the 
code must 
allocate 
variables 
to 
receive 
the 
data 
from 
the 
rows 
and 
set 
the pointers 
in Ldesc. 


See 
the 
following 
discussion ./ 


/. 
associate Lcursor 
with 
SELECT 
s tat erne n t 
• / 
$ 
declare Lcursor 
cursor 
for Lid; 


/. 
open Lcursor; 
create active 
set 
./ 
$ 
open Lcursor; 


/. 
loop 
through 
rows 
in 
act ive 
set 
./ 
for(;;) 


/. 
fetch 
next 
row 
from 
the 
act ive set 
.; 
$ 
fetch, Lcursor 


using descriptor 
Ldesc; 


/. 
process 
data if 
fetch 
returned 
a 
row ./ 
if 
(sqlca.sqlcode == 0) 


I 
I/. 
process 
data ./ 
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else 


j" 
out 
of 
data 
"j 
break; 


After including the header files and declaring the relevant 
variables. the program selects the stores database as the 
current database. Once the query has been stored in the string 
q_string. it is PREPAREd and associated with the identifier 
q_id. Since the statement is a query, the program then 
DECLAREs a cursor q_cursor so that the rows that are 
returned can be examined one at a time. The OPEN statement 
that follows opens the cursor and defines an active set of rows 
for the SELECT statement. 


The complex part of this program fragment follows the 
DESCRIBE statement and is not shown in detail. The sqlda 
component q_desc->sqld now has the value 2, since two 
columns were selected from the orders table. 
q_desc->sqlvar[O] is the sqlvar_struct structure that 
contains information on the order 
num column of the 
orders table. q_desc->sqlvar[l] is the sqlvar_struct 
structure that contains information on the order_date 
column of the orders table. q_desc->sqlvar[O].sqltype, for 
example, gives the RDSQL data type of the first column 
(order_num) requested. 


It is your responsibility to allocate memory storage for each of 
the variables returned by the query. You must set the sqldata 
pointer for each value returned to the location that will receive 
the value. This process may require aligning data types with 
proper word boundaries. You can use the rtypalign function 
described in Chapter 5 for this purpose. You can also change 
the RDSQL data type to the data type with which you want to 
work. 


In this illustration, the DESCRIBE statement allocated 
memory for the necessary number of sqlvar_struct 
structures. It filled in sqltype, sqlname, and set to NULL the 
pointers sqldata and sqlind. It is your responsibility to set 
sqldata and sqlind (if desired) to point to appropriate 
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memory. If you do not use the DESCRIBE statement to create 
the sqlvar_struct structures, you must remember to set the 
indicator variable pointers to NULL. 


The example program unload.ec at the end of this chapter 
illustrates the use of the sqlda structure. 
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Parameterized SELECT Statements 


Parameterized SELECT statements are statements in which 
input variables are to be supplied at runtime. Since 
DESCRIBE statements examine only the select-List-that is, 
the list of column names or expressions in the SELECT 
clause-they do not tell you about parameters in the WHERE 
clauses. You must know the number of parameters in the 
SELECT statement and their data types. Unless you are writ- 
ing a general-purpose, interactive interpreter, you generally 
have this information. If you do not have it, you must write 
code that determines not only how many question marks (?) 
appear in the dynamic query, but also to what data type they 
belong. 


When you know the number of parameters and their data 
types, you have two options: either declare an equal number of 
host variables, or allocate memory for an sqlda structure that 
you will use to pass data to the query. 


Using Host Variables 


If the host variables corresponding to the parameters in the 
SELECT statement are hvarl, hvar2, and hvar3, you must 
execute the OPEN statement as in the following program 
fragment. 
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$include sqlca 


/* declare 
$ 
long 
$ 
Ion g 
$ 
long 


parameter 
hvar1; 
hvar2; 
hvar3; 


variables 
*/ 


/* make stores 
the current database 
*/ 
$ 
database stores; 


/ * pre par e the 
s e Ie c t 
s tat eme n t 
* / 
$ 
p r epa r e Li d 
from 
"select 
order_num, 
customer_num 
from orders 
where order_date = ? 
or pa:d_date = ? 
or ship_date = ?"; 


/* associate Lcursor with 
SELECT 
statement 
*/ 
$ 
declare Lcursor cursor 
for Lid; 


/* 
among other 
things, 
the next 
section of 
code 
assigns values 
to hvar1, 
hvar2, 
and hvar3 
*/ 


/* 
open Lcursor; 
create active set 
*/ 
$ 
open Lcursor 


using $hvarl, $hvar2, 
$hvar3; 


Using the sqlda Structure 


If there are parameters in the SELECT statement and you 
choose to input values through an sqlda structure, you must 
allocate sufficient memory and supply the following data: sqld 
(= number of parameters), sqlvar, and for each parameter 
sqltype, sqIlen (for char data only), sqldata, and sqIind 
(which must be set to NULL). If in_vals is a pointer to the 
sqlda structure that contains the parameter data, you make 
the query with the following statement: 


$ 
open Lcursor 
using descriptor 
in_vals; 
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Parameterized Non-SELECT Statements 


The situation for non-SELECT statements that contain 
parameters is essentially the same as for SELECT statements, 
except that the EXECUTE rather than the OPEN statement is 
used to indicate the parameters. If the number of parameters 
and their data types are known at compile time, an RDSQL 
statement that has been PREPAREd with the identifier 
stateid can be run with the statement: 


$ 
execute stateid using $hvar1. 
$hvar2. 
$hvar3; 


If the number of parameters is not known until runtime and 
the parameter data is entered into the sqlda structure pointed 
to by in_vaIs, the dynamic statement is run with the 
statement: 


$ 
execute stateid using descriptor 
in_vals; 


Compiling ESQL/C Routines 


The code that you write with ISFORMIX·ESQLlC statements must 
be preprocessed before you can use the C compiler. The 
INFORMIX-ESQLlC preprocessor converts the embedded state- 
ments to C language code. The resulting file can then be com- 
piled with the C compiler to create an object file, which in turn 
must be linked with the INFORMIX-ESQLlC libraries, as well as 
your own. You can use the esqI command file that is installed 
with INFORMIX·ESQLlC to perform all these tasks. 
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UNIX Systems 


To preprocess and compile a C program that contains 
INFORMIX·ESQLlC statements on UNIX systems, give its file 
name the extension .ec and enter the following command in 
response to your system prompt: 


e s q I 
[-e ] [-0 the r a r 9 s ... ] [-0 
0 u t f i Ie] 
\ 
sqlf i le.ec 
[othersrc.c 
... ] 
\ 
[otherobj.o ... ][-Iyourlib ... J 


where sqlfile.ec is your C program and outfile is the name of 
the executable output file. esqI first preprocesses the embed· 
ded RDSQL statements in sqlfile.ec and, if successful, produces 
a file sqlfile.c. If the environment variable INFORMIXDIR 
has been properly set (see Appendix C), esqI passes all other 
arguments (-otherargs), sqlfile.c, and other C source files 
(othersrc.c) straight through to the C compiler cc to produce 
sqlfile.o and othersrc.o. These files are then linked, along 
with other C object files (otherobj.o) that are included on the 
command line, with the appropriate INFORMIX-ESQLlC library 
routines. You must explicitly include your own special libraries 
(for example, libm.a for mathematical functions). 


The -e option allows you to request just the preprocessor step 
with no compilation or linking. 


DOS Systems 


To preprocess a C program that contains INFORMIX-ESQL/C 
statements on DOS systems, give the file the extension .EC 
and enter the following command in response to your system 
prompt: 


ESQLC SQLFILE.EC 


where SQLFILE.EC is your C program. 
ESQLC, if successful, 
produces a file SQLFILE.C that is ready to be compiled by 
your compiler. All INFORMIX-ESQLlC statements have been con- 
verted into C code. If you have several INFORMIX-ESQL/C files, 
they must be preprocessed one at a time. 
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Lattice C Compiler. 
The compilation procedure for Version 
3.00 of the Lattice C Compiler follows. The compilation must 
seek the include files in C:\informix\incl (compiler option 
-iC: \informix \incl). You can use other compiler options as 
appropriate. The syntax to produce SQLFILE.OBJ using the 
medium memory model is as follows: 


LC -mp -iC:\informix\incl SQLFILE 


The syntax for the large memory model is as follows: 


LC -Ip -iC:\informix\incl SQLFILE 


When you link all the object files you have created to form 
an executable file, you must include the INFORMIX·ESQLlC library 
(MLIBSQL.LIB for the medium memory model and 
LLIBSQL.LIB for the large memory model) that is located in 
\informix\lib. If you use the medium memory model, the 
syntax is as follows: 


LINK CP+SQLFILE1+SQLFILE2+... ,SQLRUN,NUL, 
\informix\1 ib\MLIBSQL[+YOURLIB]+LCP 


If you use the large memory model, the syntax is as follows: 


LINK CP+SQLFILE1+SQLFILE2+ ... ,SQLRUN,NUL, 
\informix\1 ib\LLIBSQL[+YOURLIB]+LCP 


In this example, your object files are SQLFILEl, SQLFILE2, 
... , and the executable file will be named SQLRUN.EXE. If 
you want a program listing, replace NUL with the name of the 
file to contain the listing. 
YOURLIB is the name of any other 
library you require (such as LCMP, if you use the special math 
functions). 
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Microsoft C Compiler. 
To compile and link using the Microsoft 
C compiler and the medium memory model, you can use the 
following command line: 


c I 
-AM 
s q 1f i Ie. C 
... -I \ i n for mix \ inc I 
-I ink 
informix\1 ib\MLIBSQL 


With the large memory model you can use the following com- 
mand line: 


cl 
-AL 
sql f i le.c ... -I\informix\incl 
- 1ink 
i n for mix \ lib \ L L I BSQL 


where sqlfile.c is the name of the preprocessed C source file. 


Examples 


The four example programs in this section become increasingly 
more complicated. Each of the first three examples displays 
the names of all the customers in the stores table whose last 
names begin with C through Z on the screen. The first uses a 
SELECT statement with no free parameters. The second uses 
a PREPARE statement on a query with an unknown parame- 
ter in the WHERE clause. The third is similar to the second, 
but uses the DESCRIBE statement to fill an sqlda structure 
rather 
than using host variables. 


The fourth example demonstrates many of the features of 
INFORMIX-ESQL/C by providing the code to analyze an arbitrary 
SELECT statement and to create an unloaded system file con- 
taining the data from the resulting table with a bar ( I ) delim- 
iter between the fields. 
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demol.ec 


#include <stdio.h> 
$include sqlca; 


main() 


:$char 
fname[15J; 
$char 
Iname[20]; 
i n t 
i· 


printf( 
"DEMO 1 Sample ESQL 
program running.\n\n"); 


$database stores; 


$declare democursor 
cursor 
for 
select 
fname, 
Iname 
i n t 0 
$ f name, 
$ I name 
from customer 
where 
Iname > "e"; 


$open democursor; 


for 
(;;) 
1$fetch democursor; 
if 
(sqlca.sqlcode) 
break; 
p r i nt f ('IO/oS %s \ n" , f name, 
I name) ; 
I' 
I 
$close democursor; 


pr i nt f ("\nProgram Over. \n"); 
i 
I 
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demo2.ec 


#include <stdio.h> 
$include 
sqlca; 
$include 
sqlda; 


rna i n ( ) 


struct 
sqlda 
-demo 
esc; 
$char 
demoquery[80 
$char 
queryvalue:2 
$char 
fname[20J; 
$char 
Iname:20j; 


/ - 
The sen ext 
f 0 uri i n e s 
h a v e 
h a r d-w ire d bot h 
- 
the 
query 
and 
the 
value 
for 
the parameter. 
- 
This 
i n for rna t ion 
co u I d 
h a v e 
bee n 
en t ere d 
- 
from 
the 
t e r min a I 
and 
p I acedin tot he 
s t r i n 9 s 
- 
demo que r y 
and 
que r y val ue, 
res p e c t i vel y . 
-/ 
s prj n t f ( demo que r y, 
'1O/0S %s", 
"select 
fname, 
Iname 
from customer", 
"wh ere 
I name 
> 
? "); 
s p r i n t f ( que r y val ue, "e"); 


printf("DEM02 
Sample 
ESQL 
program running.\n\n"); 


$database 
stores; 
$prepare 
qid 
from $demoquery; 
$declare 
democursor 
cursor 
for 
qid; 
$open 
democursor 
using $queryvalue; 


if 
(sqlca.sqlcode) 
p r i n t f ('1O/0S 
%d \ n" , 
"sqlca.code, 
after 
the 
cursor 
open, 
is", 
sqlca.sqlcode); 


for 
(;;) 


I 
I 
$fetch 
democursor 
into $fname, 
$Iname; 
if 
(sqlca.sqlcode) 
break; 
printf('I0/os %s\n", 
fname~ 
Iname); 


I 
I 
if 
(sqlca.sqlcode 
!= SQLNOTFOUND) 
P r in t f ('1O/0S %d\n", 
"sqlca.code, 
after 
fetch, 
is", 
sqlca.sqlcode) ; 


$close 
democursor; 
pr i nt f ("\nProgram Over. \n"); 


I 
I 
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demo3.ec 


#include <stdio.h> 
$include sqlca; 
$include sqlda; 


ma i n ( ) 


struct 
sqlda 
°demodesc; 
Schar 
demoquery:80~; 


Schar queryvalue-2- 
Schar 
Iname:20:;- 
- 


Schar 
Iname[20:; 


JOT he sen ext 
lou r 
lin e s 
ha ve 
ha r d-w ire d bot h 


o 
the query and 
the value lor 
the parameter. 


o 
T his 
i n lor ma t ion 
co u I d ha ve bee n en t ere d 


o 
I rom the 
t e rmin a I and 
p I acedin tot he s t r i ngs 


o 
demoquery and queryvalue, 
respectively. 
o j 
spr i nt I (demoquery, 
"%s %s", 
"select 
Iname, 
Iname 
Irom customer", 
"wh ere 
I name > 
? "); 
s p r i nt I ( que r yval ue, 
"C"); 


printl("DEM03 Sample ESQL program running.\n\n"); 
$database stores; 
$prepare qid 
Irom $demoquery; 
$declare democursor cursor 
lor 
qid; 
$open democursor 
using $queryvalue; 


p r i n t I ("Ofos 
Ofod \ n" • 
"sqlca.code, alter 
the cursor 
open, 
is", 
. sqlca.sqlcode); 


$describe qid 
into demodesc; 


jO Print 
out 
what 
DESCRIBE returns 
OJ 
prsqlda(demodesc->sqlvar); 
prsqlda(demodesc->sqlvar+1) ; 


jO 
Assign 
the da 
a pointers 
OJ 
demodesc->sqlvar 
0: .sqldata 
Iname; 
demodesc->sqlvar 
1J .sqldata = Iname; 
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for 
(;;) 


I 
I 
$fetch 
democursor 
using 
descr iptor 
demodesc; 
p r i n t f (" s q I ca. cod e, 
aft e r 
f etc h. 
i s %d \ n" • 
sqlca.sqlcode); 
if 
(sqlca.sqlcode) 
break; 
printf('I0/os %s\n". 
fname, 
Iname); 
, 
I 
$close 
democursor; 
pr i nt f ("\nProgram Over. \n"); 


prsqlda(sp) 
register 
struct 
sqlvar_struct 
·sp; 


printf("type 
printf("len 
pr intf("data 
pr i ntf ("i nd 
pr i nt f ("name 


%d\n", 
sp->sqltype); 
%d \ n", 
s p->s q I len) ; 
% I x \ n", 
s p->s q I d a t a ) ; 
%Ix\n", 
sp->sqlind); 
%Ix\n", 
sp->sqlname); 
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unload.ec 


The following code contains a minimal main( ) routine that 
makes stores the current database and calls the function 
unload( ). 


The function unload( ) is defined next. It takes two argu- 
ments: a string that contains a SELECT statement and a 
string that contains the name of a file. The structure of the 
code follows the pattern outlined earlier in this chapter in the 
section "Non-Parameterized SELECT Statements." 


The SELECT statement passed to unloadO is PREPAREd 
and, if successful, is DESCRIBEd into the sqlda structure 
pointed to by udesc. 


If the DESCRIBE was successful, the output file is opened and 
three major steps are performed. First, *udesc is analyzed to 
determine the type and memory requirements of each item in 
the select-list of the SELECT statement. Second, memory 
(buffer) is allocated to receive a row of the table returned by 
the SELECT statement. Third, pointers (coI->sqldata) are 
set in the allocated memory to receive each item in the select- 
list. 


A cursor is DECLAREd for the SELECT statement and the 
cursor is OPENed. The next section of code loops through a 
series of FETCHes until there are no more rows in the active 
set (sqlca.sqlcode != 0). In the loop, each item in a row is 
retrieved and written out to the output file with a delimiter ( I ) 
between each item. A count is kept of the number of rows. 


At the end, if the process was successful, a message is written 
to standard output, giving the number of rows unloaded. 


2-34 Examples 


$include 
sqlca; 
$include 
sqlda, 
$include 
sqltypes; 


#include <stdio.h> 
#deline 
DSTRSZ 
40 


rtypalign(); 


maine) 
1 
$ 
database stores; 
u n loa d ( tt Se lee t 
• 
from 
c u s 1 orne r tt 
I 
"c U st. u n I tI) ; 


register 
char 
'pos; 
register 
int 
len; 
register 
int 
i; 
char 
decstr'DSTRSZ'; 
struct 
sqld~ 
'udesc; 
struct 
sqlvar 
struct 
FILE 
'unllile: 
char 
delim= '1'; 


c h a r 
• b u I fer 
= 
NUL L ; 
in t 
cc; 


in t 
size; 
char'malloc(}; 


unload 
(slctstmt, 
$char'slctstmt; 
c h a r 
• f n arne; 


{ 


I name) 


'co I ; 


$ 


$ 


prepare 
usqlobj 
from $slctstmt; 
i I 
( 
sq I ca. sq I code 
= 
0 
) 


l 
.b 
I" 
d 
descrl 
e 
usq 
obj 
Into 
u 
esc; 
i I 
( 
sqlca.sqlcode = 
0 
) 


{il 
( 
(unllile 
= 
fopen(lname,"w") )= NULL) 


[ 
Iprintf(stderr,"Cannot 
open 
file 
'%s'\n", 
Iname); 
re t urn 
} 


;' 
Step 
1: 
analyze 
udesc 
to 
determine 
type 
and memory 
requirements 
of 
each 
item 
in 
the 
select 
list. 
, 
I 
size 
0; 
for 
(col= udesc->sqlvar, 
i 
= 
0' 
swi tch(col->sql type) 
< 
udesc->sqld; 
col++, 
i++) 


case 
SQLSMFLOAT: 
size 
= 
r typal i gn(s i ze,CFLOATTYPE); 
col->sqltype 
= 
CFLOATTYPE; 
co I->sq I I en 
= 
r t ypms i ze (CFLOATTYPE, 0) ; 
size += col->sqllen; 
break; 


case 
SOLFLOAT: 
size = 
rtypal ign(size,CDOUBLETYPE); 
col->sqltype = 
CDOUBLETYPE; 
col->sqllen 
= 
rtypmsize(CDOUBLETYPE,O); 
size += col->sqllen; 
break; 


case 
SOLM:lNEY: 


case 
SOL(jECIMAL: 
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, 
) 
Ien--, pos--; 
del im; 


size = rtypal ign(size,CDECIMALTYPE); 
col->sqltype = CDECIMALTYPE; 
col->sql len = 
rtypmsize(CDECIMALTYPE,O); 
size += col->sqllen; 
break; 


delau It: 
size = rtypal ign(size,CFIXCHARTYPE); 
col->sqllen = rtypwidth(col->sqltype,col->sqllen)+l; 
col->sqltype = CFIXCHARTYPE; 
size += col->sql len +1; 
I 
I' Step 2: Allocate memory to receive a 
row 01 
the table returned 
• 
by the SELECT statement. 
The pointer pos has an 
integer 
value equal 
to the number 01 bytes occupied by the 
row. 


• I bull e r 
= ma II 0 c ( s i ze) ; 
il 
( buller == NULL) 
IIprinll(stderr,"Out 
01 memory\n"); 
return 


I' Step 3: Set pointers 
in 
the allocated memory to receive each 
• 
item 
in 
the select 
list. 


• I size 
0; 
lor 
(col 
= udesc->sqlvar, 
i = 0; 
i < udesc->sqld; 
col++, 
i++) 
Isize = rtypalign(size,col->sqltype); 
col->sqldata = size + buller; 
size += col->sqllen; 
il 
( col->sqltype 
!= CDEClMALTYPE 
size++; 
: 
I' Step 4: 
Fetch each 
row 01 
the query, 
convert 
to ASCII 
lormat, 
and 
• 
write to the output 
Ii Ie. 


• I 
$ 
declare usqlcurs cursor 
lor usqlobj; 
$ 
open usqlcurs; 
$ 
letch usqlcurs using descriptor udesc; 
whi Ie (sqlca.sqlcode == 0 
) 
Ilor 
(col=udesc->sqlvar, 
udesc->sqld; i > 0; 
col++, 
i--) 
Iil 
( col ->sqltype == CDECIMALTYPE 
) 
I 
dectoasc(col->sqldata,decstr,DSTRSZ,-l); 
Idchar(decstr,DSTRSZ,decstr); 
Iputs(decstr,unlli Ie); 
putc( 
i == 1 ? '\n' 
: 
delim,unllile); 


I 
else 


: 
len 
col->sql len; 
pos 
col->sqldata + 
len - 
1; 
while 
( len> 1 && 'pos ==' 


• (++pos) = 
i == 1 ? '\n' 
: 
'(++pos) = 0; 
Iputs(col->sqldata,unlli Ie); 


$ 
Iletch usqlcurs using descriptor udesc; 
I 
Iclose(unl I i Ie); 
il 
(buller) 
I ree(buller); 
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, 
I 
if 
( 
sqlca.sqlcode 
&& 
sqlca.sqlcode 
1= SOlNOTFOUND ) 
I 
j. 
display 
ERROR message"j 
fprinlf(slderr."unload 
failed 
sqlcode 
%d\n". 
sqlca.sqlcode); 
: 


else 
I 
fprinlf(slderr,"unloaded %d 
rows\n" 
. 
sqlca.sqlerrd[2); 
I 
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RDSQL Statements 


This chapter describes those RDSQL statements that can be 
embedded in a C program. Use it along with Chapter 2, where 
you find definitions of C structures, host variables, indicator 
variables, and so on, as well as instructions on how to prepare a 
C program for the INFORMIX-ESQL/C preprocessor. 


The RDSQL statements listed below are described in detail on 
the following pages. Because the SELECT statement and its 
clauses (FROM, INTO, WHERE, GROUP BY, HAVING, 
ORDER BY, and INTO TEMP) require special attention, they 
are described in a later section of this chapter. Those RDSQL 
statements and statement options that apply only to dynami- 
cally defined statements are marked with a cross symbol (t). 
Since you need dynamically defined statements only in 
advanced applications, you can ignore these statements and 
options for most purposes. 


For single-user DOS systems, several of the RDSQL statements 
have no effect. These are marked below with a double 
dagger (:j:). 
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ALTER INDEX 
ALTER TABLE 
BEGIN WORK 
CLOSE 
CLOSE DATABASE 
COMMIT WORK 
CREATE AUDIT 
CREATE DATABASE 
CREATE INDEX 
CREATE SYNONYM 
CREATE TABLE 
CREATE VIEW 
DATABASE 
DECLARE 
DELETE 
DESCRIBE+ 
DROP AUDIT 
DROP DATABASE 
DROP INDEX 
DROP SYNONYM 
DROP TABLE 
DROP VIEW 
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EXECUTEt 
FETCH 
FLUSH 
GRANT:j: 
INSERT 
LOCK TABLE 
OPEN 
PREPAREt 
PUT 
RECOVER TABLE 
RENAME COLUMN 
RENAME TABLE 
REVOKE:j: 
ROLLBACK WORK 
ROLLFORWARD DATABASE 
SELECT 
SET LOCK MODE 
START DATABASE 
UNLOCK TABLE:j: 
UPDATE 
UPDATE STATISTICS 


ALTER INDEX 


Overview 


Use the ALTER INDEX statement to cluster a table in the 
order of an existing index or to release an index from the 
cluster attribute. 


Syntax 


ALTER INDEX index-name TO [NOT] CLUSTER 


Explanation 


ALTER INDEX 
are required keywords. 


index-name 
is the RDSQL identifier of an existing index. 


TO 
is a required keyword. 


NOT 
is an optional keyword. 


CLUSTER 
is a required keyword. 


Notes 


1. The TO CLUSTER option causes RDSQL to reorder the 
rows in the physical table to agree with the order of index- 
name. Reordering causes the entire file to be rewritten and 
requires sufficient disk space to maintain two copies of the 
table. The process may take a long time. 


2. Since there can be only one clustered index per table, you 
must use the NOT option to release the cluster attribute 
from one index before assigning it to another. The NOT 
option does not affect the physical table; it merely drops the 
cluster attribute on index-name from the system catalogs. 
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3. When RDSQL executes ALTER INDEX with the TO 
CLUSTER option, it locks the table in EXCLUSIVE mode. 
If some other process is using the table to which index- 
name belongs, RDSQL cannot execute ALTER INDEX with 
the TO CLUSTER option and returns an error. 


4. If you execute this statement within a transaction, it cannot 
be rolled back. It can, however, be rolled forward. 


5. Over time you can expect the benefit of an earlier cluster to 
disappear. You can recluster the table by issuing another 
ALTER INDEX TO CLUSTER statement on the clustered 
index. 


6. You do not need to drop a cluster index before issuing 
another ALTEH INDEX TO CLUSTER statement on a 
currently clustered index. 


Examples 


The following example creates two indexes on the orders table 
and clusters the physical table in ascending order on the 
custorner_nurn column. Later, the example clusters the phy- 
sical table in ascending order on the order_Durn column. 


$ 
create unique 
index 
ix_ord 
on orders 
(order_num) ; 
$ 
create cluster 
index 
i><-cust 


on orders 
(customer_num) ; 


$ 
a I t e r 
index 
i x_cust 
to not cluster; 


$ 
a.1 t e r 
index 
ix ord to cluster; 
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Related Statements 
CREATE INDEX 
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ALTER TABLE 


Overview 


Use the ALTER TABLE statement to add a column to a table, 
to delete a column from a table, or to modify the data type of a 
column. 


Syntax 


ALTER TABLE table-name 
:ADD (neweal-name neweal-type 
[BEFORE aldeal-name]. ...) 
IDROP (aldeal-name, ...) 
IMODIFY (aldeal-name neweal-type [NOT NULL] , ...>:, ... 


Explanation 


ALTER TABLE 
are required keywords. 


table-name 


ADD 


neweol-name 


neweol-type 


BEFORE 


oldeol-name 
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is the name of an existing table. 


is a keyword you use to add a column to 
table-name. 


is the name of the column you want to add. 


is either the data type of the column you are 
adding or the data type of the column you 
are modifying. 


is an optional keyword you use to indicate 
where you want neweol-name placed in the 
list of columns. The default is at the end of 
the list of columns. 


is the name of an existing column. 


DROP 


MODIFY 


NOT NULL 


Notes 


is a keyword you use to drop a column from 
table-name. 


is a keyword you use to change the data type 
of an existing column. 


are optional keywords. 


1. You can use one or more of the ADD clause, the DROP 
clause, or the MODIFY clause and can place them in any 
order. Use a comma to separate the clauses. The actions 
are performed in the order specified. If any of the actions 
fail, the entire operation is canceled. 


2. You cannot add a SERIAL column to a table that is not 
empty. 


3. You cannot use a NOT NULL clause in an ALTER TABLE 
statement when you add a new column, since RDSQL inserts 
a NULL value into the new column for all existing rows. 


4. If a column is currently designated as NOT NULL, you can 
modify it to allow NULL values by specifying the same 
column name and data type in the MODIFY clause of an 
ALTER TABLE statement. If a column allows NULL 
values but currently does not contain any NULLs, you can 
change it to a NOT NULL column by specifying the same 
column name and data type in the MODIFY clause along 
with the NOT NULL keywords. 


5. You must own table-name, have DBA privilege, or be 
granted ALTER permission to use ALTER TABLE. 


6. Do not use the ALTER TABLE statement within a 
transaction; it cannot be rolled back. 


7. Altering a table on which a view depends may invalidate the 
view. 
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Examples 


$ 
alter 
tab I ei t em s 
add 
(i tem_weight 
decimal (6.2) 
before totalJr ice): 


$ 
a I t e r 
tab lei t ems 
drop (totaIJrice): 


$ 
a I t e r 
tab lei t ems 
modi fy 
(manu_code char(4»: 


Related Statements 


RENAME COLUMN, RENAME TABLE 
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( 


BEGIN WORK 


Overview 


Use the BEGIN WORK statement to start a transaction 
(a sequence of database operations that are terminated by the 
COMMIT WORK or ROLLBACK WORK statement). 


Syntax 


BEGIN WORK 


Explanation 


BEGIN WORK 
are required keywords. 


Notes 


1. See Chapter 1 for a full description of transactions. 


2. Each row affected by an UPDATE, DELETE, or INSERT 
statement during a transaction is locked and remains locked 
throughout the transaction. A transaction that contains a 
large number of such statements, or that contains state- 
ments affecting a large number of rows, may exceed the 
limits placed by your operating system on the maximum 
number of simultaneous locks. If you encounter this error, 
you may need to lock the entire table before beginning the 
transaction. 


See the section "Locking" in Chapter 1 for a more detailed 
description of table-level and row-level locking in INFORMIX- 
ESQL/C. 
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Related Statements 


COl\lMIT \\'ORK. ROLLBACK WORK 
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( 


CLOSE 


Overview 


Use the CLOSE statement when you no longer need to refer to 
the active set of a SELECT cursor or when you want to flush 
the insert buffer and close an INSERT cursor. 


Syntax 


CLOSE cursor-name 


Explanation 


CLOSE 


cursor-name 


Notes 


is a required keyword. 


is the name of a cursor that has been 
DECLAREd for a SELECT or an INSERT 
statement. 


1. If cursor-name is associated with a SELECT statement, the 
CLOSE statement puts the cursor in a closed state and 
leaves the active set undefined. 


2. After you CLOSE a SELECT cursor, you cannot execute a 
FETCH statement until you reopen it. 


3. If cursor-name is associated with an INSERT statement, 
the CLOSE statement flushes any rows in the buffer into 
the database and closes the cursor. 


4. After you CLOSE an INSERT cursor, you cannot execute a 
PUT or FLUSH statement until you reOPEN the cursor. 
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5. The global variables sqlca.sqlcode andsqlca.sqlerrd[2] 
indicate the result of each FLUSH and CLOSE statement 
for an INSERT cursor. 
IfRDsQL successfully inserts the 
buffered rows into the database, it sets sqlca.sqlcode to 
zero and sqlca.sqlerrd[2] to the number of rows inserted 
into the database. 
If RDSQL encounters an error while 
inserting the buffered rows into the database, it sets 
sqlca.sqlcode to a negative number (specifically, the 
number of the error message) and sets sqlca.sqlerrd[2] to 
the number of rows successfully inserted into the database. 
Buffered rows following the last successfully inserted row 
are discarded. In this case, it does not close the cursor. 


6. Although the COMMIT WORK and ROLLBACK WORK 
statements close all open cursors, do not use them for this 
purpose. Explicitly CLOSE each INSERT cursor before 
committing the work, so you can check that the insertion 
was successful. 


7. 
RDSQL does not provide a global variable containing the 
total number of rows successfully inserted into the database 
with an insert cursor. If you want to know that total 
number of inserts performed, you must set a counter in your 
program and increment it upon each PUT statement. 


Examples 


$ 
close 
~curs; 


$ 
close 
i_curs; 


Related Statements 


DECLARE,FETCH,FLUSH,OPEN,PUT 
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CLOSE DATABASE 


Overview 


Use the CLOSE DATABASE statement to close the current 
database and to leave the program with no current database. 


Syntax 


CLOSE DATABASE 


Explanation 


CLOSE DATABASE 
are required keywords. 


Notes 


1. Following the CLOSE DATABASE statement, the only 
legal RDSQL statements are CREATE DATABASE, 
DATABASE, and DROP DATABASE. 


2. The CLOSE DATABASE statement is useful when you 
want to drop the only remaining database. 


Related Statements 


CREATE DATABASE, DROP DATABASE 
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COMMIT WORK 


Overview 


Use the COMMIT WORK statement to commit all 
modifications made to the database since the last BEGIN 
WORK statement. 


Syntax 


COMMIT WORK 


Explanation 


COMMIT WORK 


Notes 


are required keywords. 


1. Use the COMMIT WORK statement when you are satisfied 
that the changes to the database made since the last 
BEGIN WORK statement are what you want. 


2: The COMMIT WORK statement closes all open cursors. 


3: See the section "Transactions" in Chapter 1 for details. 


Related Statements 


BEGIN WORK, ROLLBACK WORK 
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CREATE AUDIT 


Overview 


Use the CREATE AUDIT statement to create an audit trail file 
and to start writing the audit trail. 


Syntax 


CREATE AUDIT FOR table-name IN "pathname" 


Explanation 


CREATE AUDIT 
FOR 


table-name 


IN 


pathname 


Notes 


are required keywords. 


is the name of the table for which you 
want to create an audit trail file. 


is a required keyword. 


is the full pathname for the audit trail 
file. It must be enclosed in quotation 
marks. 


1. You create audit trails to keep a record of all modifications 
of a table. An audit trail is a complete history of all addi- 
tions, deletions, and updates to the table. RDSQL can use the 
audit trail to reconstruct the table from a backup copy made 
at the time the audit trail is created. (See the RECOVER 
TABLE statement.) See the section "Audit Trails" in 
Chapter 1 for more information. 


2. If an audit trail file with the same pathname already exists, 
the CREATE AUDIT statement does nothing. If an audit 
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trail file for the same table exists with a different pathname, 
RDSQL returns an error. 


3. Make a backup copy of your database files as soon as you 
run the CREATE AUDIT statement, but before you make 
any further changes to the database. (See RECOVER 
TABLE for an example.) If possible, put the audit trail file 
on a different physical device from the one that holds your 
data, so that a failure of one does not damage the data on 
the other. 


4. Audit trails slow RDSQL slightly because each alteration of 
the database is recorded in the audit trail file, as well as in 
the database files. 


5. You must own table-name or have DBA status to use the 
CREATE AUDIT statement. 


6. You must set execute permission for all directories below 
root in pathname for each class of user (owner, owner's 
group, and public) that accesses your database. 


Examples 


On a UNIX system: 


create 
audit 
for 
orders 
in 
"/dev/sa~e/audord"; 


On a DOS system: 


create 
audit 
for 
orders 
in 
"\KEEP\SAFE·.AUDORD"; 


Related Statements 


DROP AUDIT, RECOVER TABLE 
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CREATE DATABASE 


Overview 


Use the CREATE DATABASE statement to create a new 
database. RDSQL creates the system catalogs that contain the 
data dictionary describing the structure of the database. The 
database you create automatically becomes the current data- 
base. 


Syntax 


CREATE DATABASE database-name [WITH LOG IN "pathname"J 


Explanation 


CREATE 
are required keywords. 
DATABASE 


database-name 
is the name you assign to the database. 
database-name can be a host string variable 
containing the name of the database you want 
to create. 


WITH LOG IN 
are optional keywords. 


pathname 


Notes 


is the full pathname of the transaction log- 
file. pathname must be enclosed in quotation 
marks. 


1. 
RDSQL creates a subdirectory in the current directory with 
the name database-name.dbs. All of the system catalogs. 
data, and index files will be placed in this subdirectory. 
except for tables that you explicitly instruct RDSQL to create 
elsewhere. 
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2. 
A database name can be up to 8 (DOS) or 10 (UNIX) 
characters in length and can contain only letters, digits, and 
underscores ( 
). The first character must be a letter. If 


you store more than one database in a single directory, the 
database names must be unique. 


3. For a user to have access to a database on UNIX systems, 
the user must have execute (search) permission for each 
directory in the full pathname of database-name.dbs, as well 
as appropriate database privileges (see the GRANT 
statement). 


4. 
See Appendix B for a detailed description of the system 
catalogs. 


5. The \VITH LOG IN clause creates a transaction log file. 
Without this file, you cannot use the BEGIN WORK, COM- 
MIT WORK, or the ROLLBACK WORK statements. You 
can use the START DATABASE statement to assign a log 
file to an existing database. See the section "Transactions" 
in Chapter 1 for further details. 


6. You can execute CREATE DATABASE only when there is 
no current database. 
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\. 


Examples 


On a UNIX system: 


$ 
create database stores 
with 
log 
in "/s/log/stores.log"; 


On a DOS system: 


$ 
create database stores 
with 
log 
in 
"\LOG\STORES.LOG"; 


Related Statements 


DROP DATABASE, GRANT, START DATABASE 
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CREATE INDEX 


Overview 


Use the CREATE INDEX statement to create an index for 
one or more columns in a table and optionally to cluster the 
physical table in the order of the index. 


Syntax 


CREATE [UNIQUE I DISTINCT) {CLUSTER) INDEX index-name 
ON table-name (column-name [ASC I DESC)....) 


Explanation 


CREATE INDEX 


UNIQUE 


DISTINCT 


CLUSTER 


index-name 


ON 


table-name 
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are required keywords. 


is a keyword you use to prevent duplicate 
entries in the column or the composite 
column to which the index applies. 


is a keyword that is synonymous with 
UNIQUE. 


is an optional keyword that causes the 
physical table to be ordered according to 
the order of the index. 


is the RDSQL identifier you want to assign 
to the index. You must assign a different 
identifier to each index in the database. 


is a required keyword. 


is the name of the table containing the 
column or columns you want to index. 


column-name 


DESC 


Notes 


is the name of a column you want to 
index. To create an index that applies to 
several columns. enter a list of column 
names separated by commas. All the 
columns you specify must belong to the 
same table. 


is a keyword that specifies an index that 
RDSQL maintains in ascending order. 
ASC is the default. 


is a keyword that specifies an index that 
RDSQL maintains in descending order. 


\,-- 


1. When RDSQL executes the CREATE INDEX statement. it 
locks table-name in EXCLUSIVE mode. If another process 
is using table-name, RDSQL cannot execute CREATE 
INDEX and returns an error. 


2. You can include up to eight columns in a composite index. 


3. The total length of all columns indexed in a single CREATE 
INDEX statement cannot exceed 120 bytes. 


4. See the section "Indexing Strategy" in Chapter 1 for a 
discussion of indexing strategy. 


5. The CREATE CLUSTER INDEX statement fails if a 
CLUSTER index already exists. 


6. When there is more than one column listed. the concatena- 
tion of the set of columns is treated as a single composite 
column for the purpose of indexing. 


7. If you use the CREATE INDEX statement in a transaction. 
it cannot be rolled back. However. it can be rolled forward. 


CREATE INDEX 3-25 


8. Descending indexes are not used to optimize queries. They 
are used to improve the performance of ORDER BY clauses 
in SELECT statements. 


Examples 


$ 
create unique 
index 
i_ordnum 
on orders 
(order_num); 


$ 
create cluster 
index 
i_ordnum2 
on orders 
(order_num desc); 


Related Statements 


ALTER INDEX, DROP INDEX 
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CREATE SYNONYM 


Overview 


Use the CREATE SYNONYM statement to provide an 
alternative name for a table or view. 


Syntax 


CREATE SYNONYM synonym FOR table-name 


Explanation 


CREATE 
SYNONYM 


synonym 


FOR 


table-name 


Notes 


are required keywords. 


is an RDSQL identifier. 


is a required keyword. 


is the name of a table or view. 


1. A synonym is effective only for the user who creates it. 


2. A user has no privileges under a synonym that were not 
granted for the table to which it applies. 


3. When a synonym is created in an INFORMIX-ESQL/C program, 
the owner of the synonym is the person who runs the 
program. 
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4. 
Once created, a synonym persists until the owner of the 
synonym executes the DROP SYNONYM statement. This 
property distinguishes the synonym from the alias that you 
can use in the FROM clause of a SELECT statement. The 
alias persists only until the completion of the SELECT 
statement. 


5. Do not use the CREATE SYNONYM statement in a 
transaction; it cannot be rolled back. 


6. The synonym name cannot be the same as a table name in 
the database. 


Examples 


$ 
create synonym cust 
for 
customer; 


Related Statements 


DROP SYNONYM, SELECT 
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CREATE TABLE 


Overview 


Use the CREATE TABLE statement to create a new table in 
the current database. 


Syntax 


CREATE [TEMP] TABLE table-name 
(column-name datatype [NOT NULL], ...) 
[IN "pathname"] 


Explanation 


CREATE TABLE 


TEMP 


table-name 


column-name 


datatype 


NOT NULL 


IN 


pathname 


are required keywords. 


is an optional keyword. 


is the identifier you want to assign to the 
table. The first 8 (DOS) or 10 (UNIX) 
characters must be unique within a 
database. 


is the identifier you want to assign to 
each column. 


specifies the data type for each column. 
(See the following list for valid data 
types.) 


are optional keywords. 


is an optional keyword. 


specifies the full pathname in which you 
want to store the database table, with no 
extension to the filename. The pathname 
cannot be longer than 64 characters, and 
must be contained within quotes ("). 
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In UNIX systems, a pathname is of the 
form 


[/directory-name/···lfilename 


and in DOS systems the form of a 
pathname is 


[\\directory-name\\ ...lfilename 


(the double backslashes are necessary for 
the C compiler; continue to use single 
backslashes at the operating system 
level). 


Valid data types in RDSQL follow. (A detailed discussion of data 
types is contained in Chapter 9, "Database Structure and 
Integrity," in the INFORMIX-SQL User Guide.) 


CHAR(n) 
A character string of length n (where 1 
<= n <= 32,767). 


SMALLINT 
A whole number from - 32,767 to 
+32,767. 


INTEGER 
A whole number from -2,147,483,647 to 
+2,147,483,647. 


DECIMAL[(m[,n])] 
A decimal floating-point number with a 
total of m « = 32) significant digits (pre- 
cision) and n « = m) digits to the right 
of the decimal point (scale). 


SMALLFLOAT 
A binary floating-point number 
corresponding to the "float" data type in 
the C language. On small machines, 
RDSQL implements SMALLFLOAT as 
DECIMAL(8). 


FLOAT 
A binary floating-point number 
corresponding to the "double" data type 
in the C language. On small machines, 
RDSQL implements FLOAT as 
DECIMAL(16). 
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MONEY[(m[,n])] 


SERIAL[(n)] 


DATE 


Notes 


A DECIMAL type number, displayed 
with leading $. MONEY(m) = 
DECIMAL(m,2) and MONEY = 
DECIMAL(16,2). See the section "Data- 
base Data Types," earlier in this chapter, 
for more details. 


A unique sequential integer assigned 
automatically by RDSQL. You may assign 
an initial value n. The default starting 
integer is 1. 


A date entered as a character string in 
one of the formats described in the 
following notes. 


1. 
Table names must be unique within a database. 


2. 
Column names must be unique within each table, but you 
can use duplicate names in different tables in the same 
database. 


3. 
Temporary tables created with the TEMP option last only 
for the duration of the session (that is until you exit 
INFORMIX-SQL). You may not build a PERFORM screen on a 
temporary table. 


4. 
Users with CONNECT privilege may create temporary 
tables. 


5. 
The default value for a column is NULL, unless you 
include the NOT NULL keywords after the data type of 
the column. 


6. 
If you designate a column as NOT NULL, you must enter 
a value into this column when performing an INSERT or 
UPDATE to the table. 
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7. 
By default, all users who have been granted CONNECT 
privilege to the database have all types of access to the new 
table except ALTER. To further restrict access, use the 
REVOKE statement to take all access away from PUBLIC 
(everyone on the system); then use the GRANT statement 
to designate the types of access you want to give to specific 
users. 


8. 
You can specify no more than one SERIAL column in a 
table. 


9. 
Enter DATE data types in the sequence of month, day, 
and year, with any non-numeric character, including a 
blank, as a separator. Represent the month as the number 
of the month (January = 1 or 01, February = 2 or 02, and 
so on). Represent the day as the day of the month (l or 
01, 2 or 02, and so on). The year is stored as a four-digit 
number (0001 to 9999). If you enter two digits yy for the 
year, RDSQL assumes the year is 19yy. 


The following are all acceptable representations of June 1, 
1988: 06/01/88, 6.1.88, and 6-1-1988. 


10. The DATE type is actually stored as the integer number of 
days since December 31,1899. You can sort DATE 
columns and make chronological comparisons between two 
DATE columns. 


11. The file space requirements in bytes for each data type are 


SERIAL 
SMALLINT 
INTEGER 
SMALLFLOAT 
FLOAT 
CHAR(n) 
DECIMAL(m,n) 
MONEY(m,n) 
DATE 


4 
2 
4 
4 
8 
n 
1 + m/2 
1 + m/2 
4 


On small machines, SMALLFLOAT requires five bytes, 
and FLOAT, nine bytes. 


12. Do not use the CREATE TABLE statement within a 
transaction; it cannot be rolled back. 
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se ria I ( 101) , 
char (15). 
cha r (15) , 
char(20), 
char(20). 
char(20). 
cha r (15) • 
cha r (2) • 
cha r (5) • 
char(18) 


13. If the pathname in an IN clause specifies a filename that is 
different from the table-name, always use the table-name 
(rather than the filename) to refer to the table in subse- 
quent INFORMIX-SQL statements. 


14. The pathname in an IN clause can specify any valid direc- 
tory and is not restricted to the drive or directory that con- 
tains the current database. This enables a database to 
include tables in different disk volumes, or on more than 
one drive, or on different network nodes, or on virtual 
drives. Use this feature if your database is becoming too 
large for your current disk volume. 


Examples 


The following statement creates the cust table and places the 
database files in the /u/mirage/f1uffy file: 


$ 
create 
lable cust 
( 
customer_num 
fname 
Iname 
company 
addressl 
address2 
c i Iy 
slate 
zipcode 
phone 
) 
in "/u/mi ragel II uffy"; 


The sequence of statements that creates the stores database 
follows: 


$ 
creale database stores; 


$ 
create 
table 
customer 
( 
customer_num 
fname 
I name 
company 
addressl 
address2 
c i I Y 
slate 
zipcode 
phone 
) ; 


se ria I ( 101) • 
char(15), 
cha r (15) , 
char(20), 
char(20). 
char(20), 
cha r (15) , 
char (2). 
cha r (5) . 
char(18) 
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$ 
create 
table orders 
( 
order_num 
serial(1001) , 
order_date 
date, 
customer_num 
integer, 
sh i p_i nst ruct 
char(40), 
backlog 
char(1) , 
po_num 
char( 10), 
ship_date 
date, 
ship_weight 
decimal (8,2), 


ship-,-charge 
money(S), 
pa i d_da te 
date 
) ; 


$ 
create 
table 
items 
( 
i tem_num 
sma II in t, 
order_num 
integer, 
stock_num 
smallin!, 
manu_code 
char(3) , 
quant i ty 
sma I lint, 
tota IJr i ce 
money(8) 
) ; 


$ 
create 
table stock 
( 
stock_num 
sma Iii nt, 
manu_code 
char(3) , 
description 
cha r (15) , 


unitJrice 
money(S) , 
unit 
char(4) • 
un i t_descr 
char(15) 
) ; 


$ 
create 
table manufact 
( 
manu_code 
char(3) • 
manu_name 
cha r (15) 
) ; 


$ 
create 
unique 
index 
c 
num ix 
on 
customer 
(customer 
num); 
$ 
create 
index zip_ix on customer 
(zipcode); 
- 
$ 
create 
unique 
index 
0 
num ix 
on orders 
(order 
num); 
$ 
create 
index 
0 
c 
num Ix on orders 
(customer 
num); 
$. 
create 
index. 
i=o=:num=i x 
on 
items 
(order_num); 
$ 
create 
index 
st 
man 
i x 
on 
i terns 
(stock 
num, 
manu 
code); 
$ 
create 
unique 
index-stk_man_ix 
on stocl( (stock_num, 
manu_code); 


~ 
create 
unique 
index man_cd_ix 
on manufact 
(manu_code); 


Related Statements 


CREATE DATABASE, DROP DATABASE, DROP TABLE, 
GRANT,REVOKE 
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CREATE VIEW 


Overview 


Use CREATE VIEW to create a new view based upon existing 
tables and views in the database. 


Syntax 


CREATE VIEW view-name [(column-list)] 
AS SELECT-statement [WITH CHECK OPTION] 


Explanation 


CREATE VIEW 


mew-name 


column-list 


AS 


are required keywords. 


is an RDSQL identifier. 


is a list of one or more identifiers that 
name the columns of view-name. 


is a required keyword. 


SELECT-statement 
is an RDSQL SELECT statement. 


WITH CHECK 
OPTION 


Notes 


are optional keywords. 


1. Except for the statements in the following list, you can use 
a -view in any RDSQL statement where you can use a table. 


ALTER TABLE 
CREATE INDEX 
DROP INDEX 


LOCK TABLE 
RENAME TABLE 
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The view behaves like a table with the name view-name and 
consists of the set of rows and columns returned by the 
SELECT-statement each time the RDSQL statement is exe- 
cuted using the view. The view reflects changes to the 
underlying tables with one exception. If the view is defined 
with a SELECT * clause, it has only the columns in the 
underlying tables at the time the view is created. New 
columns added subsequently to the underlying tables using 
the ALTER TABLE statement will not appear in the view. 
See the section "Views" in Chapter 1 for more information. 


2. When you do not specify column-list for view-name, the 
view inherits the column names of the underlying tables. If 
the SELECT-statement returns an expression, the corres- 
ponding column in the view is called a virtual column. You 
must provide a name for virtual columns. You must also 
provide a, column name when the select-list has duplicate 
column names when the table prefixes are stripped. For 
example, when both orders.order~Dum and 
items.order_Dum appear in the select-list, you must 
provide two separate column names to label them in the 
CREATE VIEW statement. 


3. Data types of the columns of the view are inherited from 
the tables from which they come. Data types of virtual 
columns are determined from the nature of the expression. 


4. view-name must be unique among all the tables and views 
that already exist in the database. 


5. You can define a view in terms of other views, except that 
you must abide by the restrictions on queries listed in the 
section "Querying through Views" in Chapter 1. 


6. The SELECT-statement cannot have an ORDER BY clause 
or a UNION operator, and it cannot include host variables. 


7. You must have SELECT privilege on all columns from 
which the view is derived. 
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8. The WITH CHECK OPTION clause instructs RDSQL to 
ensure that all modifications to the underlying tables made 
through the view satisfy the definition of the view. 


9. Do not use the CREATE VIEW statement within a 
transaction; it cannot be rolled back. 


Examples 


$ 
create view palo__alto as 
select 
• 
from customer 
where city = "Palo Alto"; 


Related Statements 


CREATE TABLE, DROP VIEW 
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DATABASE 


Overview 


Use the DATABASE statement to select an accessible database 
as the current database. 


Syntax 


DATABASE database-name [EXCLUSIVE] 


Explanation 


DATABASE 
is a required keyword. 


database-name is the name of the database you want to select. 
It can also be a host variable that evaluates to 
the name of a database. 


EXCLUSIVE 
is an optional keyword. 


Notes 


1. If you want to specify a database that does not reside in 
your current directory nor in a directory specified by the 
DBPATH environment variable (see Appendix C), you must 
follow the DATABASE keyword with a host variable that 
evaluates to the full pathname of the database (excluding 
the .dbs extension). 


2. The EXCLUSIVE option opens the database in an exclusive 
mode and allows only the database administrator (DBA) 
access to the database. To allow others access to the data- 
base, you must execute the CLOSE DATABASE statement 
and then reopen the database. 


3. Do not use the DATABASE statement within a transaction; 
it cannot be rolled back. 
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4. This statement closes the current database, if one exists. 


Examples 


$ 
database stores; 
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DECLARE 


Overview 


Use the DECLARE statement to assign a cursor name to a 
SELECT or INSERT statement. 


Syntax 


DECLARE cursor-name [SCROLL] CURSOR FOR 
ISELECT-statement [FOR UPDATE [OF column-list]] I 
INSERT-statement I statement-idi 


Explanation 


DECLARE 


cursor-name 


SCROLL 


CURSOR FOR 


is a required keyword. 


is an RDSQL identifier. 


is an optional keyword and can be used 
only with a SELECT cursor. 


are required keywords. 


SELECT-statement 
is an RDSQL SELECT statement. 


FOR UPDATE 


OF 


column-list 


are optional keywords. 


is an optional keyword. 


is a list of column names from the tables 
listed in the FROM clause of the 
SELECT statement. 


INSERT-statement 
is an RDSQL INSERT statement. 


statement-id 
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is the identifier of an INSERT or 
SELECT statement that has been 
previously PREPAREd. 


Notes 


1. 
You must DECLARE a SELECT cursor before it can be 
used in an OPEN, FETCH, DELETE, UPDATE, or 
CLOSE statement. You must DECLARE an INSERT 
cursor before it can be used in an OPEN, PUT, FLUSH, 
or CLOSE statement. 


2. 
You must include the SCROLL keyword in the 
DECLARE statement for a SELECT cursor if you issue a 
FETCH PREVIOUS, FETCH PRIOR, FETCH LAST, 
FETCH FIRST, FETCH CURRENT, FETCH RELA- 
TIVE, or FETCH ABSOLUTE statement. 


3. 
If you use a statement-id to identify a SELECT or 
INSERT statement, you must have previously 
PREPAREd the statement. 


4. 
cursor-name has meaning from the point at which it is 
DECLAREd to the end of the source file. This means 
that the DECLARE statement for a cursor must physi- 
cally appear before any statement that makes reference to 
the cursor. It is not a global variable that can be used in 
a separate source file. 


5. 
You may not use the FOR UPDATE clause in the 
DECLARE statement for a SELECT cursor that 
SCROLLs. 


6. 
You must use the FOR UPDATE clause in the 
DECLARE statement for a non-SCROLLing SELECT 
cursor if you will later use either the UPDATE or the 
DELETE statement with the WHERE CURRENT OF 
cursor-name option. 


7. 
If you do not specify any columns in the FOR UPDATE 
clause of a DECLARE statement, you can update any 
column in a subsequent UPDATE WHERE CURRENT 
OF statement. If you do specify one or more columns in 
the FOR UPDATE clause, you can update only those 
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columns in a subsequent UPDATE WHERE CURRENT 
OF statement. When you specify the column names in 
the FOR UPDATE clause, INFORMIX-ESQL/C can usually 
perform the updates more quickly. 


8. 
The columns in an OF column-list clause need not be in 
the select-list of the SELECT clause. 


9. 
When you DECLARE a cursor FOR UPDATE, each 
FETCH executed on that cursor locks the FETCHed row 
in exclusive mode. The lock is released when you execute 
'the next FETCH statement or when you CLOSE the cur- 
sor. See the section "Locking" in Chapter 1 for a more 
detailed description of table-level and row-level locking. 
When you execute the actions within a transaction, the 
locked rows are released only when you issue a COMMIT 
WORK or ROLLBACK WORK statement. 


10. 
You cannot DECLARE a cursor for an INSERT state- 
ment that contains an embedded SELECT statement. 


11. 
If you DECLARE a cursor for an INSERT statement 
that includes a VALUES clause containing only con- 
stants, RDSQL does not create a buffer but merely keeps 
count of the number of inserts. Such INSERTs are never 
flushed as the result of a PUT statement. Flushing 
occurs when you issue a FLUSH or CLOSE cursor state- 
ment. 
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Examples 


$ 
declare scurs cursor 
for 
select 
• 
from customer; 


$ 
declare ucurs cursor 
for 
select 
• 
from customer where customer 
num > 110 
for 
update 
0 f 
f name. 
Iname; 


$ 
declare 
icurs cursor 
for 
insert 
into stock 
values 
($stock_no. 
$man_code. $descr. $uJrice. 


$un it. 
$u_des·c); 


$ 
declare s curs scrol I cursor 
for 
select-· 
from orders 
where customer_num = 104; 


Related Statements 
CLOSE,DELETE,FETCH,FLUSH,OPEN,PREPARE, 
PUT,SELECT,UPDATE 
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DELETE 


Overview 


Use the DELETE statement to delete one or more rows from a 
table. 


Syntax 


DELETE FROM table-name 
[WHERE lcondition I CURRENT OF cursor-namelJ 


Explanation 


DELETE FROM 


table-name 


WHERE 


condition 


CURRENT OF 


cursor-name 


Notes 


are required keywords. 


is the name of the table from which you 
want to delete rows. 


is a keyword. 


is a condition of a standard WHERE 
clause (see the SELECT statement for 
further information). RDSQL deletes all 
rows that satisfy the condition in the 
WHERE clause. 


are keywords. 


is the RDSQL identifier of a previously 
DECLAREd and positioned cursor. 


1. When you create a database with transactions, each RDSQL 
statement you execute is treated as a single transaction, 
even if you do not use the BEGIN WORK and COMMIT or 
ROLLBACK WORK statements. Because each row 
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affected by the DELETE statement within a transaction is 
locked for the duration of the transaction, a single 
DELETE statement that affects a large number of rows 
locks the rows until the entire operation is completed. If 
the number of rows affected is very large, you may exceed 
the limits placed by your operating system on the maximum 
number of simultaneous locks. If this occurs, you may want 
either to reduce the scope of the DELETE statement or to 
lock the entire table before executing the statement. 


See the section "Locking" in Chapter 1 for a more detailed 
description of table-level and row-level locking in INFORMIX· 
ESQL/C. 


2. To use the WHERE CURRENT OF option, you must have 
previously DECLAREd the cursor-name with the FOR 
UPDATE option. 


3. If you use the CURRENT OF option, DELETE removes 
the row of the active set at the current position of the cur- 
sor. The cursor is left pointing between the remaining rows 
and cannot be used for DELETE or UPDATE until it is 
repositioned with a FETCH statement. 


4. The DESCRIBE statement sets sqlca.sqlwarn.sqlwarn4 
to W when a DELETE statement is PREPAREd without a 
WHERE clause. RDSQL produces the same warning if you 
PREPARE a DELETE statement, but do not EXECUTE 
it. 


5. If your database has transactions and you use the WHERE 
CURRENT OF clause, you must execute the DELETE 
statement within a transaction. 


DELETE 3-45 


Examples 


$ 
delete 
from 
items 
where order__num = $onum; 
$ 
delete 
from orders 
where current 
of query__cursor; 


These statements remove all items belonging to the order 
number set in the host variable onum from the items table 
and remove the row from the orders table pointed to by the 
cursor query_cursor. 


Related Statements 


DECLARE, INSERT, UPDATE 
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DESCRIBE 


Overview 


DESCRIBE obtains information about a statement that has 
been PREPAREd. 


Syntax 


DESCRIBE statement-name INTO sqlda-ptr 


Explanation 


DESCRIBE 


statement-name 


INTO 


sqlda-ptr 


Notes 


is a required keyword. 


is the RDSQL identifier of a previously 
PREPAREd statement. 


is a required keyword. 


is a C variable declared as a pointer to an 
sqlda structure. 


1. DESCRIBE sets sqlda-ptr to point to a sqlda structure and 
describes there the data that is retrieved when statement- 
name is executed. 


2. The DESCRIBE statement sets sqlca.sqlwarn.sqlwarn4 
to W when an UPDATE or DELETE statement is 
PREPAREd without a WHERE clause. 


3. DESCRIBE sets sqlca.sqlcode to 0 for a SELECT state- 
ment without an INTO TEMP clause and to a positive 
integer for any other RDSQL statement. You can test 
sqlca.sqlcode against the following constants that are 
defined as positive integers in the header file sqIstmtype.h 
(see Appendix A). 
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Integer 


SQ_SELECT 
SQ_SELINTO 
SQ_UPDATE 
SQ_UPDCURR 
SQ_UPDALL 
SQ_DELETE 
SQ_DELCURR 
SQ_DELALL 
SQ_INSERT 
SQ_DATABASE 
SQ_CREADB 
SQ_CLSDB 
SQ_DROPDB 
SQ_CRETAB 
SQ_CTEMP 
SQ_DRPTAB 
SQ_CREIDX 
SQ_DRPIDX 
SQ 
CREASYN 
SQ=DROPSYN' 
SQ_CREVIEW 
SQ_DROPVIEW 
SQ_ALTER 
SQ_RENTAB 
SQ_RENCOL 
SQ_GRANT 
SQ_REVOKE 
SQ_LOCK 
SQ_UNLOCK 
SQ_STATS 
SQ_BEGWORK 
SQ_COMMIT 
SQ_ROLLBACK 
SQ_STARTDB 
SQ_RFORWARD 
SQ_LDINSERT 
SQ_CREAUD 
SQ_STRAUD 
SQ_STPAUD 
SQ_DRPAUD 
SQ_RECTAB 
SQ_CHKTAB 
SQ_REPTAB 
SQ_CLSDB 
SQ_WAITFOR 
SQ_ALTIDX. 
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RDSQL Statement 


SELECT 
SELECT INTO TEMP 
UPDATE 
UPDATE (with cursor) 
UPDATE (no WHERE clause) 
DELETE 
DELETE (with cursor) 
DELETE (no WHERE clause) 
INSERT 
DATABASE 
CREATE DATABASE 
CLOSE DATABASE 
DROP DATABASE 
CREATE TABLE 
CREATE TEMP TABLE 
DROP TABLE 
CREATE INDEX 
DROP INDEX 
CREATE SYNONYM 
DROP SYNONYM 
. CREATE VIEW 
DROP VIEW 
ALTER TABLE 
RENAME TABLE 
RENAME COLUMN 
GRANT 
REVOKE 
LOCK TABLE 
UNLOCK TABLE 
UPDATE STATISTICS 
BEGIN WORK 
COMMIT WORK 
ROLLBACK WORK 
START DATABASE 
ROLLFORWARD DATABASE 
FLUSH INSERT BUFFER 
CREATE AUDIT 
START AUDIT 
STOP AUDIT 
DROP AUDIT 
RECOVER TABLE 
CHECK TABLE 
REPAIR TABLE 
CLOSE DATABASE 
SET LOCK MODE 
ALTER INDEX 


Examples 


$ 
describe state_id 
into Ldesc; 


Related Statements 
PREPARE,OPEN 
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DROP AUDIT 


Overview 


Use the DROP AUDIT statement to delete an audit trail file. 


Syntax 


DROP AUDIT FOR table-name 


Explanation 


DROP AUDIT FOR are required keywords. 


table-name 


Notes 


is the name of the table whose audit trail 
file you want to delete. 


1. Use the DROP AUDIT statement to remove the old audit 
trail file when you have made a backup of your database 
files. Use the CREATE AUDIT statement to start a new 
audit trail, and then back up the table. See the section 
"Audit Trails" in Chapter 1 for more information. 


2. You must own table-name or have DBA status to use the 
DROP AUDIT statement. 


Examples 


$ 
drop audit 
for 
orders; 


Related Statements 


CREATE AUDIT, RECOVER TABLE 
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DROP DATABASE 


Overview 


Use the DROP DATABASE statement to delete an entire 
database, including all system catalogs, indexes, and data. 


Syntax 


DROP DATABASE Idatabase-name I char-variable: 


Explanation 


DROP DATABASE 
are required keywords. 


database-name 


char-variable 


Notes 


is the name of the database you want to 
delete. 


is a host variable of type CHAR contain- 
ing the name of the database you want to 
delete. 


1. You must own all the tables in the database or have DBA 
status to run the DROP DATABASE statement success- 
fully. Otherwise, RDSQL sets sqlca.sqlcode to a negative 
value and does nothing. 


2. The DROP DATABASE statement does not remove the 
database directory if there are any files in the database 
directory other than those created for database tables and 
their indexes. 


3. You are not allowed to drop the current database. You 
must execute the CLOSE DATABASE statement first. 
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4. Do not execute the DROP DATABASE statement within a 
transaction; it cannot be rolled back. 


Examples 


$ 
drop database stores; 


Related Statements 


CREATE DATABASE, CLOSE DATABASE 
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DROP INDEX 


Overview 


Use the DROP INDEX statement to delete an index. 


Syntax 


DROP INDEX index-name 


Explanation 


DROP INDEX are required keywords. 


index-name 


Notes 


is the name of the·index you want to delete. 


1. You must be the owner of the index or have DBA privilege 
to use the DROP INDEX statement. 


2. Do not execute the DROP INDEX statement within a 
transaction; it cannot be rolled back. 


Examples 


$ 
drop 
index 
i__ordnum; 


Related Statements 


CREATE INDEX 
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DROP SYNONYM 


Overview 


Use the DROP SYNONYM statement to remove a previously 
defined synonym. 


Syntax 


DROP SYNONYM synonym 


Explanation 


DROP 
SYNONYM 


synonym 


Notes 


are required keywords. 


is an RDSQL identifier. 


1. You can drop a synonym only if you created it. 


2. When you compile a program containing a synonym, the 
synonym is replaced by the real table identifier in the com- 
piled program. Ifyou subsequently drop the synonym, the 
compiled program will still run. 


3. Do not execute the DROP SYNONYM statement within a 
transaction; it cannot be rolled back. 


Examples 


$ 
drop synonym cust; 
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Related Statements 


CREATE SYNONYM 
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DROP TABLE 


Overview 


Use the DROP TABLE statement to remove a table, along 
with its associated indexes and data. 


Syntax 


DROP TABLE table-name 


Explanation 


DROP TABLE are required keywords. 


table-name 


Notes 


is the name of the table you want to remove. 


1. When you remove a table, you also delete the data stored in 
it, the indexes on columns, any synonyms assigned to it, and 
any authorizations you have granted on the table. You also 
delete all views based on the table. 


2. You cannot drop any of the system catalog tables. 


3. You must be the owner of a table or have DBA privilege to 
use the DROP TABLE statement. 


4. Do not execute the DROP TABLE statement within a 
transaction; it cannot be rolled back. 


Examples 


$ 
drop table customer; 
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Related Statements 


CREATE TABLE 
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DROP VIEW 


Overview 


Use the DROP VIEW statement to remove a view from the 
database. 


Syntax 


DROP VIEW view-name 


Explanation 


QROP VIEW 
are required keywords. 


Vlew-name 
is the identifier of a view. 


Notes 


1. You can drop only those views that you have created. See 
the section "Views" in Chapter 1 for more information. 


2: When you drop view-name, you also drop all views defined 
in terms of view-name. 


3. Do not execute the DROP VIEW statement within a 
transaction; it cannot be rolled back. 


Examples 


$ 
drop view cust1; 
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Related Statements 


CREATE VIEW, DROP TABLE 
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EXECUTE 


Overview 


EXECUTE runs a previously PREPAREd statement. 


Syntax 


EXECUTE statement-id [USING :input-list I DESCRIPTOR sqlda:J 


Explanation 


( 


EXECUTE 


statement-id 


USING 


input-list 


is a required keyword. 


is an RDSQL identifier named in a previously 
PREPAREd statement. 


is a keyword. 


is a list of host variables to be substituted as 
values for the question marks (?) in the state- 
ment indicated by statement-id. Use this 
option when you know the number and data 
types of the PREPAREd statement. 


DESCRIPTOR is an optional keyword. 


sqlda-ptr 


Notes 


is a C variable pointer to an sqlda structure 
that describes the undefined values in the 
PREPAREd statement. 


1. Once you have PREPAREd an RDSQL statement, you can 
EXECUTE it as often as you desire. 


2. To use the USING clause, you must know the number of 
the parameters of the PREPAREd statement. The data 
type of each variable in input-list must be compatible with 
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the value expected in the PREPAREd statement for the 
corresponding parameter. 


3. The host variables in input-list can be associated with 
indicator variables if the syntax of the statement 
corresponding to statement-id permits them. 


4. Do not EXECUTE a PREPAREd SELECT statement. 
Use DECLARE with the OPEN, FETCH, and CLOSE 
statements to execute a PREPAREd SELECT statement. 


Examples 


s p r i n t f ( s 1 ,.t%s" , 
"update orders set 
po_num = ?, 
order_date = ?"); 
$ 
prepare statement_1 
from s1; 
$ 
execute statement_1 
using $po_num, $order_date; 


Related ,Statements 


DECLARE,PREPARE 
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FETCH 


Overview 


Use the FETCH statement to move the cursor to a new row in 
the active set and to retrieve the values from that row. 


Syntax 


FETCH [NEXT I !pREVIOUS I PRIOR: I FIRST I LAST I CURRENT I 
RELATIVE n I ABSOLUTE m ] cursor-name 
[INTO variable-list I USING DESCRIPTOR sqlda-ptr] 


Explanation 


FETCH 


NEXT 


PREVIOUS 


PRIOR 


FIRST 


LAST 


CURRENT 


RELATIVE n 
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is a required keyword. 


is an optional keyword indicating the 
next row in the active list. NEXT is the 
default. 


is an optional keyword indicating the 
prior row in the active list. 


is an optional keyword that is 
synonymous with PREVIOUS. 


is an optional keyword indicating the first 
row of the active list. 


is an optional keyword indicating the last 
row of the active list. 


is an optional keyword indicating the 
current row of the active list. 


is an optional keyword indicating the 
nth row relative to the current cursor 


ABSOLUTE m 


cursor-name 


INTO 


variable-list 


USING 
DESCRIPTOR 


sqlda-ptr 


Notes 


position in the active list. A negative 
number specifies before the current cur- 
sor postion. n can be either a numeric 
literal or a host variable. 


is an optional keyword indicating the mth 
row in the active list. n can be either a 
numeric literal or a host variable. 


is an RDSQL identifier of a previously 
DECLAREd cursor. 


is an optional keyword. 


is a list of host variables that contains 
the column values of the row pointed to . 
by cursor-name. 


are optional keywords. 


is a pointer to a sqlda structure that 
controls the storage of values corres- 
ponding to the columns or expressions 
returned by the SELECT statement 
associated with cursor-name. 


1. FETCH NEXT is the default condition. 


2. You must first DECLARE a SCROLL cursor before issuing 
a FETCH PRIOR, FETCH FIRST, FETCH LAST, 
FETCH CURRENT, FETCH RELATIVE n, or FETCH 
ABSOLUTE m statement. 


3. If the SELECT statement associated with the cursor has an 
INTO clause, there must be no INTO clause in any FETCH 
statement referring to that cursor. If the SELECT state- 
ment has no INTO clause, the FETCH statement must 
have one. 
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4. When the cursor points to the last row in the active set, a 
subsequent FETCH NEXT causes INFORMIX-ESQL/C to 
return a "not found" code (sqlca.sqlcode = 
SQLNOTFOUND). 


5. If you issue a FETCH PRIOR (FETCH PREVIOUS) state- 
ment when the cursor points to the first row in the active 
set, INFORMIX-ESQL/C returns a "not found" code 
(sqlca.sqlcode = SQLNOTFOUND). 


6. When you execute a FETCH ABSOLUTE n statement 
where no nth row exists in the active set, INFORMIX-ESQL/C 
returns a "not found" code (sqlca.sqlcode = 
SQLNOTFOUND). 


7. When you execute a FETCH RELATIVE n statement 
where no nth row exists in the active set,INFORMIX-ESQLlC 
returns a' "not found" code (sqlca.sqlcode = 
SQLNOTFOUND). 


8. FETCH does not lock a row unless the DECLARE state- 
ment contains a SELECT with a FOR UPDATE clause. It 
is possible to retrieve a row that is being UPDATEd or 
DELETEd by a concurrent process. 


Examples 


$ 
fetch query_curs 
into $cnum. 
$Iname; 


$ 
fetch first 
query_curs 
into $cnum. 
$Iname; 


Related Statements 


OPEN,CLOSE,DELETE,UPDATE 


3-64 FETCH 


FLUSH 


Overview 


Use the FLUSH statement to force RDSQL to insert the buffered 
rows into the database without closing the cursor. 


Syntax 


FLUSH cursor-name 


Explanation 


FLUSH 


cursor-name 


Notes 


is a required keyword. 


is the name of a cursor that has been 
DECLAREd for an INSERT statement. 


1. The global variables sqlca.sqlcode and sqlca.sqlerrd[2] 
indicate the result of each FLUSH statement. If itDSQL 
successfully inserts the buffered rows into the database, it 
sets sqlca.sqlcode to zero and sqlca.sqlerrd[2] to the 
number of rows inserted. If RDSQL is unsuccessful in its 
attempt to insert the rows into the database, it sets 
sqlca.sqlcode to a negative number (specifically, the 
number of the error message) and sets sqlca.sqlerrd[2] to 
the number of rows successfully inserted into the database. 


2. You can use the FLUSH statement to force the insertion. 
YQU cannot delay insertion by not using the FLUSH state- 
ment. RDSQL automatically flushes the buffer when it is full. 


3. Insert cursors that contain only constants in the values 
clause are not buffered. Additional PUTs cannot fill the 
buffer and trigger an automatic FLUSH. RDSQL keeps a 
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count of the number of rows to be inserted into the data- 
base, and the database is updated only when you issue a 
FLUSH or CLOSE statement. 


Caution! Exiting a program without closing the cursor leaves the 
buffer unflushed. Rows inserted into the buffer and remaining since 
the last flush are lost. Do not expect the end of program to close the 
cursor and flush the buffer. 


Examples 


$ 
flush 
icurs; 


Related Statements 


CLOSE,DECLARE,OPEN,PUT 
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GRANT 


Overview 


Use the GRANT statement to specify user access privileges to 
a database or to the tables in a database. Access privileges are 
relevant only on multi-user systems. 


Syntax 


GRANT tab-privilege ON table-name TO !pUBLIC I user-list: 
[WITH GRANT OPTION] 


GRANT db-privilege TO lPUBLIC I User-list: 


Explanation 


GRANT 


tab-privilege 


is a required keyword. 


is one or more of the following table-level 
access types (multiple privileges must be 
separated by commas): 


ALTER 


DELETE 


INDEX 


INSERT 


SELECT [(cols)] 


adds or deletes 
columns or modifies 
data types of 
columns. 


deletes rows. 


creates indexes. 


inserts rows. 


retrieves data from 
specified columns. 
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ON 


table-name 


TO 


PUBLIC 


user-list 


UPDATE [(cols)] 
changes values in 
specified columns. 


ALL [PRIVILEGES]· 
is all of the above. 


SELECT and UPDATE take column names as 
arguments, allowing you to specify columns 
that the user can select or update. Separate 
column names with commas. 


The keyword PRIVILEGES following ALL is 
optional. 


is a required keyword. 


is the name of the table for which you are 
granting access privileges. 


is a required keyword. 


is the keyword you use to specify access 
privileges for all users. 


is a list of login names for the users to whom 
you are granting access privileges. You can 
enter one login name or a series of login 
names, separated by commas. 


WJTH GRANT 
OPTION 
are optional keywords. 


db-privilege 
is one of the following database-level access 
types: 
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CONNECT 
allows access to database 
tables without permission to 
create permanent tables and 
indexes. 


RESOURCE 
allows access to database 
tables with permission to 
create permanent tables and 
indexes. 


DBA 
allows full database adminis- 
trator privileges. 


Notes 


1. You can grant privileges only on tables you create or on 
tables for which you have been given GRANT OPTION. 


2. If you do not enter any column names, the SELECT or 
UPDATE access that you grant applies to all columns. 


3. When you GRANT table-level privileges to another user 
using the WITH GRANT OPTION phrase, you give that 
user the power to GRANT the same privileges to another 
user. 


4. The CONNECT privilege allows the recipient to interact 
with the existing tables of the database with all the table- 
level access privileges except ALTER. The CONNECT 
privilege alone forbids the recipient from creating tables 
(except temporary tables) and indexes. The CONNECT 
recipient can create views. 


5. The RESOURCE privilege includes the CONNECT 
privilege and adds the permission to create tables and 
indexes. 
. 


6. The DBA privilege includes the RESOURCE privilege, as 
well as the ability to alter system catalogs, to drop, start, 
and roll forward the database, and to grant and revoke 
CONNECT, RESOURCE, and DBA privileges to and from 
other users. 


7. When you create a database, you are the Database 
Administrator and have DBA privileges. 
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8. Do not execute the GRANT statement within a transaction; 
it cannot be rolled back. 


9. The most restrictive privileges always take precedence. For 
example, when you grant RESOURCE privileges to a user 
but do not grant INDEX privileges at the table level, that 
user is not able to create indexes for that table. Similarly, 
when you grant a user CONNECT privileges and table-level 
INDEX privileges, that user is still prevented from using 
the CREATE INDEX statement. 


Examples 


When you grant CONNECT privileges to PUBLIC, all table- 
level privileges, except ALTER, are granted to everyone. The 
situation is the same as if you ran the following statements for 
each of the tables in the database: 


$ 
9 ran t 
a I Ion 
c u s t orne r 
top ubi i c ; 


$ 
rev 0 k e 
a I t e ron 
c u s t orne r 
f r orn pub lie; 


To restrict access privileges on the table level, you must first 
revoke all privileges and then grant those you want: 


$ 
rev 0 k e 
a I Ion 
c us t orne r 
f r orn pub lie ; 


$ 
9 ran t 
a I Ion 
c us t orne r 
t 0 
joe. 
rna r y ; 
$ 
9 ran t 
.s e lee t 
(f n arne. 
I n arne, 
c ornp any. 
cit y ) 
one u s t orne r 
top ubi i c ; 


Related Statements 


REVOKE 
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INSERT 


Overview 


Use the INSERT statement to insert one or more new rows 
into an existing table. 


Syntax 


INSERT INTO table-name [(column-list)] 
:VALUES (value-list) I SELECT-statement: 


Explanation 


INSERT INTO 


table-name 


column-list 


VALUES 


value-list 


are required keywords. 


is the name of the table to which you 
want to add rows. 


are the names of the columns into which 
you want to insert data. You can enter 
one column name or a series of column 
names, separated by commas. 


is a keyword. 


are the values that you want to insert 
into the columns you specified. You can 
enter one or more host variables or 
constants, separated by commas. 


SELECT-statement 
is a valid RDSQL SELECT statement. 
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Notes 


1. 
RDSQL inserts data into the columns in the specified table 
in the order in which you enter column names. It inserts 
the first value you enter into the first listed column, the 
second value into the second listed column, and so on. 


2. 
Entering column names is optional. If you omit them, 
RDSQL assumes the values are listed in the order in which 
the columns are listed in the syscolumns systems catalog. 
Unless you have subsequently used the ALTER TABLE 
statement to change the order, the order is the same as 
when the table was created. 


3. 
RDSQL inserts the rows of data that result from the 
SELECT statement into the table, just as though you had 
entered them with the VALUES keyword. 


4. 
You cannot use table-name in the FROM clause of the 
SELECT statement. The data must be selected from 
other tables. 


5. 
You cannot include an INTO TEMP clause or an ORDER 
BY clause in the SELECT statement. 


6. 
Although the values you insert do not have to be of the 
same data type as the columns themselves, they must be 
compatible. You can insert only CHAR data into CHAR 
columns and only numeric or character representation of 
numeric data into numeric columns. 


7. 
Enter a zero (0) for a SERIAL column in the INSERT 
statement if you want RDSQL to insert the next SERIAL 
value for the table. Enter a nonzero value for a SERIAL 
column that does not duplicate a value already in the table, 
if you want RDSQL to use that value. When you enter a 
nonzero value for a SERIAL column that duplicates a 
value already in the table and if a unique index is defined 
on the column, this action produces an error and 
sqlca.sqlcode is set to a negative value. 


8. 
You can use host variables in the list of values. 
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9. 
All constant CHAR and DATE values must be enclosed in 
quotation marks. 


10. As an alternative to using the NULL keyword in value-list, 
you may use a host variable with a negative indicator 
variable. 


11. When you create a database with transactions, each RDSQL 
statement you execute is treated as a single transaction, 
even if you do not use the BEGIN WORK and COMMIT 
or ROLLBACK WORK statements. Because each row 
affected by the INSERT statement within a transaction is 
locked for the duration of the transaction, a single 
INSERT statement that affects a large number of rows 
locks those rows until the entire operation is completed. If 
the number of rows affected is very large, you may exceed 
the limits placed by your operating system on the max- 
imum number of simultaneous locks. If this occurs, you 
may want either to reduce the scope of the INSERT 
statement or to lock the entire table before executing the 
statement. 


See the section "Locking" in Chapter 1 for a more detailed 
description of table-level and row-level locking in 
INFORMIX-ESQL/C. 


Caution! RDSQL makes every possible effort to perform data conver- 
sion, including converting the character string "123" into the integer 
123. When the data cannot be converted, however, INSERT stops. 
Unless you have created the database with transactions, all changes 
made up to the point where the error is encountered remain" but 
subsequent rows from the SELECT statement are not inserted. 
Data conversion also fails if the target data type cannot hold the 
value offered. For example, you cannot insert the integer 123456 
into a SMALLINT. 
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Examples 


$ 
insert 
into customer 
values 
(0, 
$f_name, 
$ I_name , $comp, 
$addr1, $addr2,"Palo Alto" 
"CA" , $zip, $phone); 


Related Statements 


DELETE, SELECT 
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LOCK TABLE 


Overview 


Use the LOCK TABLE statement to prohibit access to a table 
by other users. 


Syntax 


LOCK TABLE table-name IN :SHARE I EXCLUSIVE: MODE 


Explanation 


LOCK TABLE 
are required keywords. 


table-name 
is the name of the table you want to lock. 


IN 
is a required keyword. 


SHARE 
is the keyword you use to give other users 
read access to the table, but to prevent them 
from modifying any of the data it contains. 


EXCLUSIVE 
is the keyword you use to prevent other users 
from having any access to the table. 


MODE 
is a required keyword. 


Notes 


1. Only one lock can apply to a table at any given time. That 
iso, if a user locks a table (in either SHARE or EXCLUSIVE 
mode), no other user can lock that table in either mode 
until the first user unlocks it. 
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2. You can use the LOCK TABLE statement after a BEGIN 
WORK statement to override row-level locking during the 
transaction. Normally, each row of a table affected by a 
statement within a transaction is locked for the duration of 
the transaction. 


During transactions that affect a large number of rows, you 
may exceed the limit placed by your operating system on 
the maximum number of locks. If you lock the entire table 
after you begin the transaction, however,INFoRMIX.ESQL/C 
does not lock each row in the table. You may want to use 
this strategy when you execute a transaction that affects a 
large number of rows or every row in a table. 


See the section "Locking" in Chapter 1 for further explana- 
tion of table-level and row-level locking in INFORMIX·ESQL/C. 


Examples 


$ 
lock table orders 
in exclusive mode; 


Related Statements 


UNLOCK TABLE 
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OPEN 


Overview 


Use the OPEN statement to establish the search criteria for a 
SELECT cursor and initialize the system for subsequent 
fetches, or to set up an insert buffer for an INSERT cursor 
that references program host variables. 


Syntax 


OPEN cursor-name [USING variable-list 
I DESCRIPTOR sqlda-ptr) 


Explanation 


OPEN 


cursor-name 


USING 


variable-list 


is a required keyword. 


is an RDSQL identifier of a previously 
DECLAREd cursor. 


is an optional keyword. 


is a list of host variables, separated by com- 
mas, corresponding to the "?" parameters in 
the query associated with a SELECT cursor. 


DESCRIPTOR is an optional keyword." 


sqlda-ptr 
is a pointer to an sqlda structure that points 
to the values corresponding to the "?" parame- 
ters in the SELECT statement associated with 
a SELECT cursor. 
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Notes 


1. If cursor-name is associated with a SELECT statement, the 
OPEN statement examines the contents of the host vari- 
ables or the values pointed to by sqlda-ptr and, using these 
values for the parameters in the SELECT statement, estab- 
lishes the search criteria for determining the logical set of 
rows that satisfies the WHERE clause. This set of rows is 
called the active set. It leaves the cursor in an open state 
and pointing before the first row of the active set. 


2. The active set is a dynamic collection of rows. The active 
set is not fixed at the time that the cursor is OPENed. 


3. Once the active set for a SELECT cursor is determined, the 
host variables are not reexamined until you reopen the cur- 
sor. 


4. You cannot use indicator variables in an OPEN statement. 


5. If a SELECT cursor is already open, an OPEN statement 
closes the cursor and reopens it, creating new selection or 
insertion criteria dependent upon the current values of the 
host variables. 


6. If cursor-name is associated with an INSERT statement 
(rather than a SELECT statement), the OPEN statement 
cannot include a USING clause. 


7. If you reopen an INSERT cursor that is already open, 
RDSQL flushes the INSERT buffer. The global variable 
sqlca.sqlerrd[2] is set to the number of rows successfully 
inserted into the database. 
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Examples 


$ 
declare s curs cursor 
for 
select-· 
from orders: 
$ 
open s_curs; 


sprintt(select_l, 
''%s %s %s %s %s", 
"select o.order_num, sum(totaIJrice)", 
"f r om 
0 r de r SO, 
i 1 ems 
i tt 
I 
"where o.order_date > 
1 and o.customer_num = 
1", 
nand 
a.order 
num = 
i .order 
num" , 
"group by o.order_num"); 
- 


$ 
prepare statement 
1 from select_1; 


$ 
declare 
~curs cursor 
for 
statement_1; 


$ 
open 
~curs using $o__date, 
$c_num; 


Related Statements 
CLOSE,DECLARE,FETCH,FLUSH,PREPARE,PUT 
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PREPARE 


Overview 


PREPARE preprocesses an RDSQL statement for later 
execution. 


Syntax 


PREPARE statement-name FROM string-spec 


Explanation 


PREPARE 
is a required keyword. 


statement-name 
is an RDSQL identifier. 


FROM 
is a required keyword. 


string-spec 
is either a string constant enclosed in quota- 
tion marks or a host variable that has been 
defined as a character array or a pointer to a 
string. string-spec must contain an RDSQL 
statement. 


Notes 


1. The statement described in string-spec cannot contain host 
variables. Use a question mark (?) in places where a data 
value will be supplied as an input value in an EXECUTE or 
OPEN statement. You cannot use question marks as place- 
holders for RDSQL identifiers such as database names, table 
names, column names, and user names. 


2. When you prepare a SELECT statement for use with the 
DECLARE statement, string-spec can include a SELECT 
statement followed by a FOR UPDATE clause. 
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3. Do not use the PREPARE statement on the following 
statements: CLOSE, DECLARE, DESCRIBE, EXECUTE, 
FETCH, OPEN, or PREPARE. 


4. Do not prepare a SELECT statement with an INTO clause. 


5. statement-name is global to the source file in which it is 
prepared. You can refer to it by name in two or more 
different functions contained in the same source file. 
However, it is not like an external variable that can be used 
in a separate source file. 


6. Within a source file, statement-name can apply to only one 
RDSQL statement. Do not prepare another statement with 
the same statement-name. 


Examples 


$ 
prepare querY_2 
from 
"select 
* 
from orders 
where customer_num = ? and 
order_date> ?"; 


Related Statements 


DECLARE,EXECUTE,OPEN 
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PUT 


Overview 


Use the PUT statement to store a row in the INSERT buffer 
for later insertion into the database table. 


Syntax 


PUT cursor-name 


[:USING DESCRIPTOR sqlda-ptr I FROM host-variable-list:] 


Explanation 


PUT 


cursor-name 


is a required keyword. 


is the name of a cursor that has been 
DECLAREd for an INSERT statement. 


USING 
DESCRIPTOR are optional keywords. 


sqlda-ptr 


FROM 


variable-list 
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is a pointer to an sqlda structure that points 
to the values corresponding to the "?" parame- 
ters in the prepared INSERT statement asso- 
ciated with the cursor. 


is an optional keyword. 


is a list of host variables, separated by com- 
mas, corresponding to the "?" parameters in 
the prepared INSERT statement associated 
with the cursor. 


Notes 


1. You can execute the PUT statement only if cursor-name 
has been DECLAREd for an INSERT statement and is in 
an open state. Such a cursor is referred to as an insert 
cursor. 


2. The PUT statement puts a row in the buffer that was 
created when cursor-name was OPENed. When you flush 
the buffer (by executing a series of PUT statements, a 
CLOSE statement, or a FLUSH statement) RDSQL inserts 
the buffered rows into the database table as a block. 


3. Insert cursors that contain only constants in the values 
clause are not buffered. Additional PUTs cannot fill the 
buffer and trigger an automatic FLUSH. RDSQL keeps a 
count of the number of rows to be inserted into the data- 
base, and the database is updated only when you issue a 
FLUSH or CLOSE statement. 


4. You close a cursor by issuing a CLOSE statement. Exiting 
a program without closing an insert cursor leaves the buffer 
unflushed. Rows inserted into the buffer and remaining 
since the last flush are lost. You cannot rely on the end of 
program to close the cursor and flush the buffer. 


5. The global variables sqlca.sqlcode and sqlca.sqlerrd[2] 
indicate the result of each PUT statement. If RDSQL simply 
puts a row in the insert buffer, it sets both sqlca.sqlcode 
and sqlca.sqlerrd[2] to zero. If, as the result of a PUT 
statement, RDSQL successfully inserts a block of rows into 
the database, it sets sqlca.sqlcode to zero and 
sqlca.sqlerrd[2] to the number of rows inserted. If, as the 
result of a PUT statement, RDSQL is unsuccessful in its 
attempt to insert an entire block of rows into the database, 
it sets sqlca.sqlcode to a negative number (specifically, the 
number of the error message) and sets sqlca.sqlerrd[2] to 
the number of rows successfully inserted into the database. 
Buffered rows following the last successfully inserted row 
are discarded. 
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6. If your database has transactions, you must execute a PUT 
statement within a BEGIN WORK-COMMIT WORK or a 
BEGIN WORK-ROLLBACK WORK block. COMMIT 
WORK and ROLLBACK WORK automatically close all 
cursors. 


7. If cursor-name has been DECLAREd for a prepared 
INSERT statement that includes "?" parameters, you must 
use the PUT statement with a FROM or USING 
DESCRIPTOR clause. After the FROM keyword, you can 
list the host variable(s) containing the value(s) RDSQL sub- 
stitutes for the "7" parameters in the prepared INSERT 
statement. After the USING DESCRIPTOR keywords, you 
can specify the name of a pointer to a sqlda structure that 
points to the value(s) for the "7" parameters. 


Examples 


$ 
declare 
icurs 
cursor 
for 
insert 
into manufact 
values 
($m_code, 
$m_name); 
$ 
open 
icurs; 
$ 
put 
icurs; 


$ 
prepare 
ins_stmt 
from 
" ins e r tin t 0 
ma n u f act 
val ue s 
(?, 
?) " ; 
$ 
declare 
dIs_curs 
cursor 
for 
ins_stmt; 
$ 
open 
ins_curs; 
$ 
put 
ins_curs 
from $m_code, 
$m_name; 


Related Statements 


CLOSE,DECLARE,FLUSH,OPEN 
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RECOVER TABLE 


Overview 


In the event of a system failure, use the RECOVER TABLE 
statement to restore a database table from a backup copy of 
the table with an audit trail file. 


Syntax 


RECOVER TABLE table-name 


Explanation 


RECOVER TABLE 
are required ke~~'ords. 


table-name 


Notes 


is the name of the table you want to 
recover. 


1. Once you have recovered the table. use the DROP AUDIT 
statement to remove the contents of the audit trail file. 
Run the CREATE AUDiT statement to start a new audit 
trail file. then back up the table. See the section "Audit 
Trails" in Chapter 1 for more information. 


2. RECOVER TABLE checks that the audit trail and 


table-name have consistent record numbers for rows where 
changes have taken place. If RECOVER TABLE finds 
inconsistencies. it stops restoring the table. 


8. You must own table-name or have DBA status to use the 
RECOVER TABLE statement. 


Examples 


The following list of RDSQL statements gives a template for the 
recovery of a table. They assume that your audit trail began 
from the last backup. 


: res tor eta b I e 
from 
I as t 
b a c k uP: 


$ 
recover 
table 
customer; 


$ 
d r 0 P 
a u d i t 
for 
c u s tome r ; 


$ 
c rea tea u d i t 
for 
c u s tome r 
in" / de v / sa f e / a u do r d" : 


:ma k e 
a 
b a c k u P 
0 f 
the 
r e co v ere d 
tab Ie: 


Related Statements 


CREATE AUDIT, DROP AUDIT 
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RENAME COLUMN 


Overview 


Use the RENAME COLUMN statement to change the name of 
a column. 


Syntax 


RENAME COLUMN table.oldcolumn TO neu'Column 


Explanation 


RENAME COLUMN 
are required keywords. 


table 
is the name of the table containing the 
column whose name you want to 
change. This is a required item in the 
statement. 


oldcolumn 
is the name of the column you want to 
rename. 


TO 
is a required keyword. 


newcolumn 
is the new name you want to assign to 
the column. 
neu~column must satisfy 
the requirements for an RDSQL 
identifier and cannot duplicate another 
column name in the table. 


Notes· 


1. You can RENAME a column of a table only when you own 
the table. have DBA privilege. or ha\'e been granted ALTER 
permISSIOn. 
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2. Do not use the RENAME COLUMN statement in a 
transaction; it cannot be rolled back. 


Examples 


$ 
rename column customer.customer_num to c_num; 


Related Statements 


ALTER TABLE, CREATE TABLE, INSERT, DROP 
TABLE, RENAME TABLE 
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RENAME TABLE 


Overview 


Use the RENAME TABLE statement to change the name of a 
table. 


Syntax 


RENAl\lE TABLE o/dname TO neuname 


Explanation 


RENAME TABLE 
are required keywords. 


oldname 
is the name of the table you want to 
rename. 


TO 
is a required keyword. 


newname 
is the new name you want to assign to 
the table. 


Notes 


1. You can RENAME a table only when you own the table, 
have DBA privilege, or have been granted ALTER 
permission on the table. 


2. Do not execute the RENAME TABLE statement within a 
transaction; it cannot be rolled back. 
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Examples 


This example moves the quantity column to the third place. 


$ 
create 
table 
xxx 
( i t elll.-n um 
sma I lin t , 
ordernum 
integer, 
qua n tit Y 
sma I lin t , 


stoc~num 
smallint, 
manu_code 
char(4), 


totalJrice 
money(8) 
) ; 
$ 
insert 
into 
xxx 
select 
item_num, 
order_num, 
quantity, 
stock_num, 
manu_code, 
tot a IJ rice 
from 
items; 
$ 
drop 
table 
items; 
$ 
rename 
table 
xxx 
to 
items; 


Related Statements 


ALTER TABLE, CREATE TABLE, INSERT, DROP 
TABLE, RENAME COLUMN 


3-90 RENAME TABLE 


REVOKE 


Overview 


Use the REVOKE statement to remove another user's access 
privileges for a table. Access privileges are relevant only on 
multi-user systems. 


Syntax 


REVOKE :tab-priuilege ON table-name I db-privilege: 
FROM :PUBLIC I user~list: 


Explanation 


REVOKE 


tab-priL'ilege 


is a required keyword. 


isone or more of the following table-level 
access privileges, separated by commas: 


ALTER 


DELETE 


INDEX 


INSERT 


SELECT 


UPDATE 


adds or deletes columns 
or modifies data types of 
columns. 


deletes rows. 


creates indexes. 


i~lserts rows. 


retrieves data. 


changes column values. 


ON 


ALL [PRIVILEGES] is all of the above. 


is a required keyword. 
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table-name 


db-priuilege 


is the name of the table for which you are 
revoking access privileges. 


is one of the following database-level access 
types: 


CONNECT 


RESOURCE 


DBA 


allows access to database 
tables without permission to 
create permanent tables and 
indexes. 


allows access to database 
tables with permission to 
create permanent tables and 
indexes. 


allows full database 
administrator privileges. 


FROM 


PUBLIC 


user-list 


Notes 


is a required keyword. 


is the keyword you use to revoke access 
privilege from all users. 


is a list of login names for the users whose 
access privilege you are revoking. You can 
enter one login name or a series of login 
names, separated by commas. 


1. Do not execute the REVOKE statement within a 
transaction; it cannot be rolled back. 


2. You can revoke database-level access privileges only if you 
have DBA status. 


3. You can revoke only table-level access privileges that you 
have granted to another user. 


4. You cannot revoke privileges from yourself. 
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.J. Although you can grant UPDATE and SELECT priyileges 


for specific columns, you cannot revoke these priyileges 
column by column. If you revoke UPDATE or SELECT 
priyileges from a user, RDSQL automatically revokes all 
UPDATE and SELECT privileges you have ever granted to 
that user for table-name. You can then regrant prh'ileges 
, for specific columns. 


6. Only a DBA recipient can revoke the DBA privilege from 
another recipient. If the database creator grants DBA 
privileges to another user, that person can revoke the DBA 
privilege from the database creator. 


I. If you revoke the DBA or RESOURCE privilegE: from one 
or more users. they are left with the CONNECT privilege. 
To reyoke all database privileges from users with DBA or 
RESOURCE status, you must revoke CONNECT as well as 
DBA or RESOURCE. 


Examples 


$ 
revoke 
delete, 
update 
one u s tome r 
from 
j 0 h n, 
rna r y : 


Related Statements 


GRANT 
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ROLLBACK WORK 


Overview 


Use the ROLLBACK WORK statement to undo all database 
modifications since the last BEGIN WORK statement. 


Syntax 


ROLLBACK WORK 


Explanation 


ROLLBACK WORK are required keywords. 


Notes 


1. See the section "Transaction" in Chapter 1 for further 
details. 


Examples 


$ 
r 0 I I b a c k 
wo r k ; 


Related Statements 


BEGIN WORK, COMMIT WORK 
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ROLLFORWARD DATABASE 


Overview 


Use the ROLLFORWARD DATABASE statement to cause 
RDSQL to apply the transactions in the transaction log file to a 
backup copy of your database, recovering all completed 
transactions. 


Syntax 


ROLLFORWARD DATABASE database-name 


Explanation 


ROLLFORWARD 
are required keywords. 
DATABASE 


database-name 
is the name of a database. 


Notes 


1. After the database is rolled forward, it is in an exclusive 
mode with no transactions. 


2. See the section "Transactions" in Chapter 1 for more 
information. 


Related Statements 


BEGIN WORK, COMMIT WORK, START DATABASE, 
ROLLBACK WORK 
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SELECT 


Overview 


Use the SELECT statement to query the current database. 


The SELECT statement can include up to eight clauses. Only 
the SELECT clause and the FROM clause are required. 


Syntax 


SELECT clause [INTO clause] FROM clause 
[WHERE clause] 
[GROUP BY clause] 
[HAVING clause] 
[ORDER BY clause] 
[INTO TEMP clause] 


See the section "The SELECT Statement" later in this chapter 
for detailed descriptions of these clauses. 
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SET LOCK MODE 


Overview 


Use the SET LOCK MODE statement to determine whether or 
not subsequent RDSQL calls wait for a locked row to become 
unlocked. 


Syntax 


SET LOCK MODE TO [NOT] WAIT 


Explanation 


SET LOCK MODE 
are required keywords. 


TO 
is a required keyword. 


NOT 
is an optional keyword. 


WAIT 
is a required keyword. 


Notes 


1. The TO NOT WAIT option causes RDSQL to return an error 
if a statement attempts to alter or delete a row (or to 
SELECT a row FOR UPDATE) that another process has 
locked. This is the default situation; that is, if you have not 
issued a SET LOCK MODE statement previously. The 
NOT option is relevant, therefore, only when you have 
previously executed SET LOCK MODE TO WAIT and 
wapt to return to the default state. 


2. The TO WAIT option causes RDSQL to wait on an attempt 
to alter or delete a row (or to SELECT a row FOR 
UPDATE) that another process has locked until the locked 
row becomes unlocked. 
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3. Use the SET LOCK MODE TO WAIT statement with 
extreme caution. If the locking process fails and does not 
remove the lock, your statement could wait indefinitely. 


4. This feature is available only on systems that have 
record-level locking and applies only to row-level locking. 
An attempt to access a row in a table that is locked IN 
EXCLUSIVE MODE returns an error. 
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START DATABASE 


\lverview 


Use the START DATABASE statement to start a new 
transaction log file. 


Syntax 


START DATABASE database-name WITH LOG IN "file-name" 


Explanation 


START 
are required keywords. 
DATABASE 


database-name 
is the name of a database. 


WITH LOG IN 
are required keywords. 


file-name 


Notes 


is the full name of the transaction log file. 
file-name must be enclosed in quotation 
marks. 


1. Use the START DATABASE statement only if you change 
the name of your transaction log file or if you want to start 
recording transactions in a database that was created 
without transactions. 


2. See the section "Transactions" in Chapter 1 for full details. 
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Related Statements 


BEGIN WORK, COMMIT WORK, CREATE DATABASE, 
ROLLBACK WORK, ROLLFORWARD DATABASE 


3-100 START DATABASE 


UNLOCK TABLE 


Overview 


Use the UNLOCK TABLE statement to unlock a table that 
you previously locked with the LOCK TABLE statement. 


Syntax 


UNLOCK TABLE table-name 


Explanation 


UNLOCK TABLE 
are required keywords. 


table-name 
is the name of the table you want to 
unlock. 


Notes 


1. Within a transaction, an UNLOCK TABLE statement has 
no effect. 


Related Statements 


LOCK TABLE 
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UPDATE 


Overview 


Use the UPDATE statement to change the values in one or 
more columns of one or more rows in a table. 


Syntax 


UPDATE table-name SET :column-name = expr[, ... )1 
:(column-list) I *: = (expr-list): 
[WHERE :condition I CURRENT OF cursor-name:) 


Explanation 


UPDATE 
is a required keyword. 


table-name 
is the name of the table that contains the 
row(s) you want to update. 


SET 
is a required keyword. 


columncname 
is the name of a column you want to update. 


expr 
is any combination of column names, 
constants, host variables, arithmetic operators, 
or an RDSQL subquery that returns a single row 
of one value. 


column-list 
is a list of the names of the columns you want 
to update. 


* 
refers to all columns in table-name. 


expr-list 
is a list of expressions that represent values 
corresponding to the columns in column-list 
or the columns represented by the asterisk 
notation. The list can include an RDSQL 
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• 


WHERE 


condition 


subquery that returns a single row of multiple 
values. 


is an optional keyword. 


is a condition for a standard WHERE clause 
made up of a search condition that compares 
the values in one column to the values in 
another column, to a host variable, or to a con- 
stant. (For further information, refer to the 
explanation of WHERE clauses in the section 
"The SELECT Statement," at the end of this 
chapter.) 


CURRENT OF are keywords. 


cursor-name 


Notes 


is the RDSQL identifier of a previously 
DECLAREd cursor. 


1. expr can be a SELECT statement in parentheses that 
adheres to standard rules for subqueries. The SELECT 
statement can return no more than one value except when 
included in an expr-list. 


2. You cannot use a SELECT statement that retrieves data 
from table-name. 


3. The number of column names included in the column-list 
must equal the number of values produced in the expr-list. 


4. Although the value returned by expr does not have to be of 
the same data type as column-name, it must be compatible 
with the column-name. You can put only CHAR data into 
CHAR columns and only numeric or character representa- 
tions of numeric data into numeric columns. 


5. If you use the CURRENT OF option in the WHERE clause, 
RDSQL updates the current row of the active set and leaves 
the cursor on the same row. 
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6. If you do not specify any columns in the FOR UPDATE 
clause of a DECLARE statement, you can update any 
column in a subsequent UPDATE WHERE CURRENT OF 
statement. If you do specify one or more columns in the 
FOR UPDATE clause, you can update only those columns 
in a subsequent UPDATE WHERE CURRENT OF state- 
ment. When you specify the column names in the FOR 
UPDATE clause, RDSQL can usually perform the updates 
more quickly. 


7. For databases with transactions, all RDSQL statements 
executed within a BEGIN WORK and COMMIT 
WORK/ROLLBACK WORK block are treated as a single 
transaction. Because each row affected by an UPDATE 
statement within a transaction is locked for the duration of 
the transaction, a single UPDATE statement that affects a 
.large number of rows will lock those rows until the entire 
operation is completed. If the number of rows affected is 
very large, you may exceed the limits placed by your operat- 
ing system on the maximum number of simultaneous locks. 
If this occurs, you may want either to reduce the scope of 
the UPDATE statement or to lock the entire table before 
executing the statement. See the section "Locking" in 
Chapter 1 for a more detailed description of table-level and 
row-level locking in RDSQL. 


Caution! 
IfRDsQL encounters an error while performing an 
UPDATE, the operation stops. Unless you have created the data- 
base with transactions, all database changes made up to the point 
where the error is encountered remain, but subsequent rows are not updated. 


A data conversion error is an example of an error that stops an 
UPDATE operation. Common data conversion errors include 
attempting to insert numeric data into a CHAR column, or attempt- 
ing to insert numeric values that exceed the limits of the data type 
of the column. For example, you cannot insert the integer 123456 
into a SMALLINT column. 


If you omit the WHERE clause, RDSQL assumes you want to update 
every row in the table. 
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Examples 


$ 
update 
stock 
set 
unit-.price = 
unit-.price ·1.04 
where manu_code = 
"HRO"; 


$ 
update 
stock 
set 
• 
(5. 
"NRG". 
"tennis 
racquet". 
"295.00", 
"case", 
"10/case") 
where 
stOCk_num = 
5 
and manu_code = 
"NRG"; 


$ 
update 
customer 
set 
(fname, 
company. 
address2) = 


(''Mar ie", 
''Mar ie's Sports", 
"P. 
O. 
Box 
3621") 
where 
customer_num = 103; 


$ 
update 
tablel 
set 
(coil, 
col2. 
col3) 
= 
«select 
min 
(ship_charge), 
max 
(ship_charge) 
from orders), "07/01/1986") 
where col4 = 1001; 


Related Statements 


SELECT, DELETE, INSERT 
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UPDATE STATISTICS 


Overview 


Use the UPDATE STATISTICS statement to cause the 
number of rows in a table to be recorded in the systables 
catalog. 


Syntax 


UPDATE STATISTICS [FOR TABLE table-name] 


Explanation 


UPDATE STATISTICS 
are required keywords. 


FOR TABLE 
are optional keywords you use when 
you want to update the statistics for 
a single table. 


table-name 
is the name of the table for which 
you want the statistics updated. 


Notes 


1. UPDATE STATISTICS is effective only when there is a 
current database. 


2. 
RDSQL uses the data generated by UPDATE STATISTICS 
to optimize searching strategy. When you have modified a 
table extensively, use UPDATE STATISTICS to improve 
the efficiency of queries. 


3. 
RDSQL does not update the statistics unless you execute the 
UPDATE STATISTICS statement. 


4. When you do not use the FOR TABLE clause, UPDATE 
STATISTICS updates all the tables in the current database. 
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The SELECT Statement 


Overview 


Use the SELECT statement to query the current database. 


The SELECT statement is made up of the following eight 
clauses. Only the SELECT clause and the FROM clause are 
required. If the INTO clause is present, it must precede the 
FROM clause. 


Syntax 


SELECT clause 
[INTO clause] FROM clause 
[WHERE clause] 
[GROUP BY clause] 
[HAVING clause] 
[ORDER BY clause] 
[INTO TEMP clause] 


These have the following syntax: 


SELECT [ALL I DISTINCT I UNIQUE] select-list 


INTO variable-list 


FROM :[OUTER] table-name [table-alias] I outer-expr: [....] 
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WHERE condition 


A condition is a collection of one or more search conditions 
connected by the logical operators AND, OR, or NOT. Exam- 
ples of search conditions are as follows: 


1. Comparison Condition 


a. expr rel-op expr 


b. expr [NOT) BETWEEN expr AND expr 


c. expr [NOT) IN (value-list) 


d. column-name [NOT) LIKE "string" 


e. column-name [NOT) MATCHES "string" 


f. column-name IS [NOT) NULL 


2. Join Condition (a comparison condition among columns of 
the joined tables) 


3. Condition with a Subquery 


a. expr rel-op IALL I ANY I SOME: (SELECT-statement) 


b. expr [NOT) IN (SELECT-statement) 


c. [NOT) EXISTS (SELECT-statement) 


GROUP BY column-list 


HAVING condition 
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ORDER BY column-name [ASC I DESCH, ...J 


INTO TEMP table-name 


Explanation 


The following pages explain each of the syntax elements. A 
few basic concepts are defined here. 


1. An expression consists of a column name, a host variable, or 
a constant, or any combination of these connected by the 
arithmetic operators: 


Operator 


+ 


* 
/. 


Operation 


addition 
subtraction 
multiplication 
division 


The result of the operation must make sense. For example, 
you cannot divide 16 by Jones. 


Host variables in expressions must have a dollar sign ($) or 
a colon (:) in front of them. 


RDSQL has two functions that can be used wherever a con- 
stant can be used. TODAY always returns your system 
date. USER returns a string containing the current user's 
name. On UNIX systems, this is the login name, while on 
multi-user DOS systems, this is the machine name. 


An expression can also be one of the aggregate or one of the 
date functions. Do not include both an aggregate function 
and a column in an expression. The aggregate and date 
functions that you can use in RDSQL statements are defined 
at the end of this chapter. 
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A CHAR column may have subscripts so that only a portion 
of the column value is involved in the expression. The 
notation for subscripting a column is column-name[m, n], 
where you want the mth through the nth characters of 
column-name. m must be less than or equal to n. 


2. A relational operator is one of the following: 


Operator 


!= or < > 
> 
>= 
< 
<= 


Operation 


equal 
not equal 
greater than 
greater than or equal 
less than 
less than or equal 


For CHAR expressions, greater than means "after" in 
ASCII collating order, where lowercase letters are after 
uppercase .letters, and both are after numerals. 


For DATE expressions, greater than means later in time. 


Notes 


1. The clauses of the SELECT statement are explained in 
detail on the following pages. Briefly, SELECT names a list 
of columns or expressions to be retrieved, INTO names the 
host variables to receive the data, FROM names a list of 
tables, WHERE sets conditions on the rows, GROUP BY 
groups rows together, HAVING sets conditions on the 
groups, ORDER BY orders the selected rows, and INTO 
TEMP puts the results into a temporary table. 


2. When the SELECT statement returns no rows, RDSQL 
returns a "no rows found" code (sqlca.sqlcode = 
SQLNOTFOUND). See the section "Error Handling and 
the sqlca Structure" in Chapter 2 for a full explanation. 


3. If a SELECT statement returns more than one row or if it 
is dynamically defined, you must use a cursor to FETCH 
one row at a time (see Chapter 1). 
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4. It is sometimes helpful to think of the SELECT statement 
as follows: 


When you list more than one table in the FROM clause, 
RDSQL behaves as though it were creating a composite table 
that is the Cartesian product of all the tables in the FROM 
clause. That is, the rows of the new table are constructed 
by taking all the possible combinations of rows from all the 
tables listed in the FROM clause. If there is a WHERE 
clause, RDSQL eliminates from this new table all rows that 
do not meet the conditions of the WHERE clause. This 
modified table is returned to the SELECT clause, where all 
columns not listed are eliminated. The resulting table is 
what the SELECT statement returns. 
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SELECT Clause 


Overview 


Use the SELECT clause to specify the data you want to 
retrieve from one or more tables in a database. 


Syntax 


SELECT [ALL I DISTINCT I UNIQUE] select-list 


Explanation 


SELECT 


ALL 


DISTINCT 


UNIQUE 


select-list 


Notes 


is a required keyword. 


is a keyword that causes RDSQL to select all 
rows that satisfy the WBERE clause, without 
eliminating duplicates. This keyword is the 
default. 


is a keyword that causes RDSQL to eliminate 
duplicate rows from the query results. 


is a keyword that is synonymous with 
DISTINCT. 


is a list of column names and/or expressions 
separated by commas. A column name must 
be unambiguous; use its table name as a prefix 
to avoid confusion. 


1. When the SELECT statement does not include a WHERE 
clause, every row is returned. 
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2. You can use DISTINCT or UNIQUE only once in a query. 


3. You can use the asterisk (*) in the select-list to select all 
columns from all the tables in the FROM clause. You can 
produce the same result by listing every column name in the 
select-list. 


4. To select all the columns from a single table, use the 
notation tablename. *. 


5. You can supply a display label for the column name or an 
expression in the select-list by following the column name or 
expression with a legal identifier. The DESCRIBE state- 
ment enters the display label into the sqlname component 
of the sqlvar_struct structure when it analyzes the 
SELECT statement. If you create a temporary table with 
the INTO TEMP clause, the column names of the tem- 
porary table are the display labels if they have been defined. 


6. If you specify an aggregate function and a column in the 
select-list, the column must be used in the GROUP BY list 
(see GROUP BY for further explanation). 


Examples 


The following examples use INTO, FROM, and WHERE 
clauses, whose syntax is defined later. 


select 
customer_num, 
Iname, 
city 
into 
$cnum, 
$Iname, 
$town 
from 
c u s tome r ; 


This statement selects columns customer_num, lname, and 
city; the FROM clause indicates that these columns are taken 
from the customer table. The values returned are placed in 
the host variables cnum, lname, and town, respectively. 
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select count(·) 
into $num 
from orders 
where customer_num = 101; 


This statement counts the number of rows in orders in which 
the customer_Dum column contains the value 101. In other 
words, it counts the number of orders made by the customer 
whose identifying number is 101. The number is placed in the 
variable Dum. 


select avg(total-.price) 


from 
items 
where order_num = 1021; 


This statement computes the average of the total-'-price 
values in those rows of items that contain an order 
Dum· 
column equal to 1021. 


select 
a+b abtotal. 
c·d cdprod 
from tablez 
into 
temp 
x; 


This statement illustrates the use of display labels. It selects 
the sum of columns a and b from tablez and gives the sum the 
iabel abtotal. Similarly, the product of columns c and d is 
labeled cdprod. These labels are the values pointed to by the 
structure element sqlvar_struct.sqIDame associated with the 
sqlda structure that receives the results of the query. 
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INTO-Clause 


Use the INTO clause to specify the host variables to receive the 
data that is retrieved by the SELECT statement. 


Syntax 


INTO variable-list 


Explanation 


INTO 


variable-list 


Notes 


is a required keyword. 


is a list of host variables (with or without 
attached indicator variables) that should agree 
in order and type with the corresponding 
columns or expressions in the select-list. 


1. You cannot use the INTO clause for dynamically created 
SELECT statements. You must use, instead, an sqlda 
structure to point to the data that is returned from the 
query. 


2. If the SELECT statement stands alone (not in a DECLARE 
statement), it must be a singleton SELECT (returning 
exactly one row) and must have an INTO clause. 


3. If the SELECT statement returns more than one row, you 
must use a cursor to FETCH the rows one at a time (see 
the section "Cursor Management" in Chapter 1). Put the 
INTO clause in the FETCH statement, rather than in the 
SELECT statement. 
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4. If the number of variables in variable-list differs from the 
number of items in the select-list, RDSQL returns a warning 
by setting sqlca.sqlwarn.sqlwarn3 to W. The actual 
number of variables transferred is the lesser of the two 
numbers. 


5. If possible, RDSQL converts the data type of each selected 
item to match that of the receiving variable. If the conver- 
sion is not possible, an error occurs and a negative value is 
returned in sqlca.sqlcode. In this case, the value in the 
host variable is unpredictable. See Chapter 4 for a 
discussion of data conversion. 


Examples 


$ 
declare 
~curs cursor 
for 
s e Ie c tin ame, 
c omp any 
into $Iname, 
$company 
from customer; 
$ 
open 
~curs; 


$ 
fetch 
~curs; 


or equivalently: 


$ 
declare 
~curs cursor 
for 
s e I e c tin ame, 
c omp any 
from customer; 
$ 
open 
~curs; 


$ 
fetch 
~curs 


into $Iname, 
$company; 
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FROM Clause 


Overview 


Use the FROM clause to specify the table or tables you want to 
select data from. 


Syntax 


FROM :table-name [table-alias] I OUTER table-name [table-alias] I 
OUTER (table-expr): [, ...J 


Explanation 


FROM 


OUTER 


table-name 


table-alias 


table-expr 


Notes 


is a required keyword. 


is an optional keyword. 


is the name of a table that contains data for 
which you are searching. 


is an optional alias for table-name. 


is one or more of the options in the syntax 
shown above, for example ..., tab 1, outer tab2 
... (See Appendix J, "Complex Outer Joins," 
for a discussion of this syntax.) 


1. Use the optional keyword OUTER to form outer joins. See 
the section "Join Conditions" later in this chapter and 
Appendix J for a detailed description of outer joins. 
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2. You can supply an alias for a table name by following the 
table name with a space and an RDSQL identifier. This 
feature is especially useful when performing self-joins (see 
the section "WHERE Clause" later in this chapter). 


Examples 


The following statement returns a row for every order: 


select 
order_num, 
Iname, 
fname 
from customer, 
orders 
where customer.customer_num 
orders. customer_num; 


In the following example, a row is returned for every order, as 
.in the above statement. However, if a customer does not have 
an order, a row is still returned. 


select 
order_num, 
Iname, 
fname 
from customer, 
outer orders 
where customer.customer_num 
orders.customer_num; 
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WHERE Clause 


Overview 


Use the WHERE clause to specify search criteria and join 
conditions on the data you want to select. 


Syntax 


WHERE condition 


Explanation 


WHERE 
is a required keyword. 


condition is a collection of one or more search conditions con- 
nected by the logical operators AND, OR, or NOT. 
A search condition can be any of the following: 


• 
Comparison Condition 
• 
Join Condition 
• 
Condition with a Subquery 


Comparison Condition 


A comparison condition can have one of the following forms: 


a. 
expr rel-op expr 


b. 
expr [NOT] BETWEEN expr AND expr 


c. 
expr [NOT] IN (value-list) 


d. 
column-name [NOT] LIKE "string" 


e. 
column-name [NOT] MATCHES "string" 
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f. 
column-name IS [NOT] NULL 


These forms are explained in the following pages. Anyone of 
these conditions can be preceded by the keyword NOT, in 
which case, the negative of the condition must be satisfied. 


Do not use an indicator variable in a WHERE clause to check 
for NULL values. RDSQL returns an error if you do. Use the IS 
[NOT] NULL option to check for NULL values. 


Syntax 


expr rel-op expr 


Explanation 


expr 


rel-op 


Examples 


is an expression. 


is a relational operator. 


select 
customer_num, 
order_date 
from orders 
where 
paid_date 
is null; 


s e I e c t 
f name, 
I name, 
c omp any 
from customer 
where ci ty[ 1 ,3J = "San"; 


select 
order_num, 
company 
from orders 
0, 
customer 
c 
where 
o.order_date > "6/12/84" 
and 
o.customer_num 
c.customer_num; 
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Syntax 


expr [NOT] BETWEEN expr AND expr 


Explanation 


expr 


NOT 


BETWEEN 


AND 


Examples 


is an expression. 


is a keyword that indicates that the expression 
to the left lies outside the range. 


is a keyword that indicates that the value of 
the· expression to its left lies in the inclusive 
range of the values of the two expressions to 
its right. 


is a required keyword. 


select 
stock_num, manu_code 
from stock 


. where 
un i tJr ice between 
$Iowprice and $hiprice 


select 
unique customer_num, 
stock_num, 
manu code 
from orders, 
items 
where order_date 
between "6/1/84" and "6/7/84" 


s e Ie c t 
f name, 
I namb 


from customer 
where zipcode not 
between "94100" and "94199" 
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Syntax 


expr [NOT] IN (value-list) 


Explanation 


expr 


NOT 


IN 


is an expression. 


is an optional keyword. 


is a required keyword. 


value-list 
is a list of values enclosed in parentheses. 


Notes 


1. The search condition is satisfied when the expression to the 
left is included in the list of items. The NOT option 
produces a search condition that is satisfied when expr is 
not in the list of items. 


2. 
valueclist can contain host variables, constants, or the 
special keyword constants TODAY and USER. 


3. TODAY is evaluated when you execute a singleton SELECT 
statement or when you PREPARE a SELECT statement. 
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Examples 


select 
Iname, 
fname, 
company 
from customer 
where state 
in 
("CA" , 
'WAtt, 
"OR") 


select 
itel'Tl-num, 
total--..price 


into $inum, 
$tprice 
from 
items 
where manu_code 
in 
("HRO", 
"HSK") 
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Syntax 


column-name [NOT] LIKE "string" 


Explanation 


column-name 
is the name of a column. 


NOT 
is an optional keyword. 


LIKE 
is a required keyword. 


string 
is a pattern of characters enclosed in quotation 
marks. 


Notes 


1. The search condition is successful when the value of the 
column on the left matches the pattern specified by string. 
You can use wildcard characters in place of other characters 
in the string: 


% 
A percent sign matches zero or more characters. 


An underscore matches any single character. 


2. The NOT option makes the search condition successful 
when the column on the left does not match the pattern 
specified by string. 
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Examples 


select 
fname, 
Iname 
from customer 
where 
Iname 
I ike 
'IO/oson"; 


This statement finds every customer representative whose last 
name ends in son. 


select 
stock_num. 
manu_code, 
unit--"price 


from stock 
wh ere 
des c rip t ion 
I ike 
·IO/ob a "%" ; 


This statement obtains stock number, manufacturer code, and 
unit price for all stock items with ball anywhere in their 
description. 
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Syntax 


column-name [NOT] MATCHES "string" 


Explanation 


column-name 
is the name of a column. 


NOT 
is an optional keyword. 


MATCHES 
is a required keyword. 


string 
is a pattern of characters enclosed in quotation 
marks. 


Notes 


1. The search condition is successful when the value of the 
column on the left matches the pattern specified by string. 
You can use three wildcard characters in place of other 
characters in the string: 


* 
matches zero or more characters 


? 
matches any single character 


[...] 
matches any of the enclosed characters, including 
character ranges as in [a-z]. A caret n as the first 
character within the brackets matches any character 
that is not listed. 
['abc] matches any character that 
is not a, b. or c. 


\ 
escapes special significance of the next character 
(used to match * or ? by writing \ * or \?) 


2. The NOT option makes the search condition successful 
when the column on the left does not match the pattern 
specified by string. 
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3. The MATCHES comparison is an RDS extension to retain 
compatibility with earlier versions of INFORMIX. 


4. Values used in a MATCHES search must be type CHAR. 


Examples 


select 
fname, 
Iname 
from customer 
where 
Iname matches "Richard*"; 


This statement selects rows in which the first seven letters of 
the last name are Richard (thus matching Richard, Richards, 
Richardson, and any others). 


select 
customer_num, 
company 
from customer 
where city matches "[A-J]*"; 


This statement provides the customer number and company 
name for all customers in cities that start with the letters A 
through J. 
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Syntax 


column-name IS [NOT] NULL 


Explanation 


column-name 
is the name of a column. 


IS NULL 
are required keywords. 


NOT 
is an optional keyword. 


Examples 


select 
order_num, 
customer_num 
from orders 
where 
paid_date 
is null; 


This statement lists those order numbers and customer 
numbers where the order has not been paid. 


You can link any number of the above described conditions 
together using the logical operators AND or OR. For example, 


select 
order_num, 
total"""'price 


from 
items 
where 
total.......price > $Ioprice 
and 
manu_code 
like "H%"; 


select 
Iname, 
customer_num 
from customer 
where 
zipcode 
between 
"93500" and "95700" 
or 
state 
not 
in 
("eA", 
'WA", 
"OR"); 
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Join Condition 


Overview 


You join two tables when you create a relationship in the 
WHERE clause between at least one column from one table 
and at least one column from the other. The effect of the join 
is to create a temporary composite table in which each pair of 
rows (one from each table) satisfying the join condition is 
linked together to form a single row. 


Syntax 


The critical elements of a SELECT statement with a join 
between two tables table] and table2 are as follows: 


SELECT clause FROM table], table2 WHERE condition 


Explanation 


SELECT clause 


FROM 


table] 


table2 


WHERE 


condition 


is any valid SELECT clause involving 
columns from table1 or table2. 


is a required keyword. 


is one of the tables in the join. 


is the other table in the join. 


is a required keyword. 


is any of the comparison conditions that 
involves columns from both table] and 
table2. 
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Notes 


1. \\Then columns from different tables have the same name, 
you must distinguish them by prefixing the table identifier 
and a period-table.column. 


2. A multiple join is a join of more than two tables. Its 
structure is similar to that shown previously, except that 
you have a join condition for more than one pair of tables in 
the FROM clause. 


3. You can also join a table to itself in a self-join. To do so, 
you must list the table name twice in the FROM clause, 
assigning it two different aliases. Use the aliases to refer to 
each of the "two" tables in the WHERE clause. 


4. An outer join occurs when every row from table] is taken, 
whether or not the join condition is met. If the join condi- 
tion is not met, the columns from table2 in the select-list 
are set to NULL values. You indicate an outer join by 
inserting the keyword OUTER before the table name table2. 


Examples 


A two-table join: 


select 
order_num, 
Iname, 
fname 
from customer, 
orders 
where 
customer .customer_num 
orders.customer_num; 


This statement lists the order number and first and last names 
of the customer's representative for each order. 
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A multiple-table join: 


select 
unique 
company, 
stock_num, 
manu_code 
from 
customer 
c, 
orders 
0, 
items 
i 
where 
C.customer 
num = O.customer 
num 
- 
- 
and 
o.order_num 
i .order_num; 


This statement yields the company name of the customer who 
ordered an item identified with the stock number and 
manufacturer code. 


Self-join: 


select 
x.stock 
num, 
x.manu 
code, 
y . s t 0 c k 
n urn, 
y. rna n u 
cod e 
from 
stock 
x, 
stock 
y 
where 
x.uni t----'pr ice > 2.5 
• 
y.unit----'price; 


This statement finds pairs of stock items whose unit prices 
differ by a factor greater than two and one-half. x and yare 
each aliases for the stock table. 


Outer join: 


select 
company, 
order_num 
from 
customer 
c, 
outer 
orders 
0 
where 
c.customer_num 
o.customer_num; 


This statement lists the company name and all order numbers 
when the customer places an order. When no order is placed, 
the company name is still listed. See the section "Outer Joins" 
in Chapter 1 and Appendix J for information about outer joins. 
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Condition with a Subquery 


Overview 


The search condition in a SELECT statement can also 


• 
Compare an expression to the result of another SELECT 
statement 


• 
Determine whether an expression is included in the results 
of another SELECT statement 


• 
Ask whether there are any rows selected by another 
SELECT statement 


SELECT statements within a WHERE clause are called 
subqueries. A subquery can return a single value, no value, or a 
set of values, but it must have only a single column or expres- 
sion in its select-list and must not contain an ORDER BY 
clause. You can make the subquery dependent upon the 
current row being evaluated by the outer SELECT statement 
(correlated subqueries). 


Syntax 


WHERE expr rel-op IALL I [ANY I SOME]: (SELECT-statement) 


WHERE expr [NOT] IN (SELECT-statement) 


WHERE [NOT] EXISTS (SELECT-statement) 


Explanation 


WHERE 


expr 


rel-op 
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is a required keyword. 


is an expression. 


is a relational operator. 


ALL 
is a keyword that denotes that the 
subquery can return zero. one. or more 
values and that the search condition is 
true if the comparison is true for each of 
the values returned. If the subquery 
returns no value, the search condition is 
true. 


ANY 
is a keyword that denotes that the 
subquery can return zero. one. or more 
values and that the search condition is 
true if the comparison is true for at least 
one of the values returned. If the 
subquery returns no value. the search 
condition is false. 


SOME 
is an alias for ANY. 


NOT 
is an optional keyword that reverses the 
truth value of the search condition. 


IN 
is a keyword that asks if expr is among 
the values returned by the following 
SELECT-statement. 


EXISTS 
is a keyword that asks if any rows are 
returned by the following SELECT- 
statement. The search condition is true 
if the subquery returns one or more rows. 


SELECT-statement 
is an RDSQL SELECT statement. 


Notes 


1. The keywords ANY and ALL can be omitted in a com- 
parison if you know the subquery will return exactly one 
value. In this case, the search condition is true if the com- 
parison is true for the expression and the value returned by 
the subquery. sqlca.sqlcode is set to a negative number 
when the subquery returns other than a single value. 
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2. 
expr IN (SELECT-statement) is equivalent to 
expr =ANY (SELECT-statement). 


3. expr NOT IN (SELECT-statement) is equivalent to 
expr != ALL (SELECT-statement). 


Examples 


select 
order_num 
from 
items 
where 
stock_num = 
9 
and 
quant i ty = 
(select 
max(quant i ty) 
from 
items 
where 
stock_num = 9); 


This statement returns a single value (the maximum number of 
volleyball nets ordered) to the outer-level query. The entire 
SELECT statement lists the order numbers for orders that 
include the maximum number of volleyball nets (stock_Dum 
= 9). 


select 
unique 
order_num 
from 
items 
where 
total-price >all 
(select 
total-price 


from 
items 
where 
order 
num 
1011); 


This statement lists the order numbers of 'all orders containing 
an item whose total price is greater than the total price on all 
the items in order number 1011. 
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I' 


select 
unique 
customer 
num 
from orders 
where 
order_num not 
in 
(select 
order_num 
from 
items 
where 
stock_num 
1); 


This statement lists all customer numbers corresponding to 
customers who have placed orders that do not include baseball 
gloves (stock_Durn = 1). 


select 
order_num. 
stock_num. 
manu_code. 
totalJrice 


from 
items 
x 
where 
totalJr ice> 
(select 
2 
• min(totalJrice) 


from 
items 
where 
order 
num 
x.order_num); 


This statement (using a correlated subquery) lists all items 
whose total price is at least twice the minimum total price for 
all items on the same order. 
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GROUP BY Clause 


Overview 


Use the GROUP BY clause to produce a single row of results 
for each group. A group is a set of rows having the same values 
for each column listed. 


Syntax 


GROl'P BY group-list 


Explanation 


GROUP BY 


group-list 


Notes 


are required keywords. 


is a column name or a list of column names, 
separated by commas, that determines the 
group. The query result contains a single row 
for each set of rows that satisfies the WHERE 
clause and contains a unique value or set of 
values in the column or columns indicated by 
group-list. 


1. Using a GROUP BY clause restricts what you can enter in 
the SELECT clause. The select-list can include aggregate 
functions for any column and/or the name of any column 
that you also list in the GROUP BY clause. Do not, how- 
ever, list any column in select-list that you do not also list 
in group-list. 


2. You cannot list a column in group-list that participates in 
select-list only as a part of an expression. 
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3. In the place of column names in group-list, you can enter 
one or more integers that refer to the position of items in 
the select-list. 


Examples 


select 
order_num, 
countC·), 
sumCtotal_JHice) 
from 
items 
group 
by 
order_num; 


This statement obtains the number of items and total price of 
all items for each order. 


select 
order_num, 
countC·), 
sumCtotal------..price) 


from 
items 
group 
by 
1; 


This statement returns the same information as the previous 
. example. 
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HA VING Clause 


Overview 


Use the HAVING clause to apply one or more qualifying 
conditions to groups. 


Syntax 


HAVINC condition 


Explanation 


HAVING 
is a required keyword. 


condition 
is a condition as defined for the WHERE clause. 


Notes 


1. Each condition compares one aggregate property of the 
group either with another aggregate property of the group or 
with a constant. 


.2. The HAVING clause generally complements a GROUP BY 
clause. If you use HAVING without GROUP BY, the 
HAVING clause applies to all rows that satisfy the WHERE 
clause. Without a GROUP BY clause, all rows that satisfy 
the WHERE clause make up a single group. 
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I, 
I 


Examples 


select 
order_num, 
avg(total-price) 


from 
items 
group 
by 
order_num 
having count(·) > 2; 


This statement returns average total price per item on all 
orders that have more than two items. 
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ORDER BY Clause 


Overview 


Use the ORDER BY clause to sort query results by the values 
contained in one or more columns. You can sort only by a 
column that you select in the SELECT clause. 


Syntax 


ORDER BY column-name [ASC I DESCH, ...J 


Explanation 


ORDER BY 
are required keywords. 


column-name 
is the name of a column by which you want to 
sort the query results. 


ASC 
is a keyword that specifies that the results are 
in ascending order. ASC is the default. 


DESC 
is a keyword that specifies that the results are 
in descending order. 


Notes 


1. You can ORDER BY up to eight columns. 


2. You can only ORDER BY columns that are named 
explicitly or implicitly in the select-list. 


3. The total length of the data in the columns included in the 
ORDER BY clause cannot be greater than 120 bytes. 
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4. 
In the place of column names. you can enter one or more 
integers that refer to the position of items in the 8elt'et-li8t. 
In this way. you can ORDER BY an expression. 


Examples 


CORRECT: 


CORRECT: 


INCORRECT: 


select 
order_date, 
ship__date 
from 
0 r de r s 
order 
by 
order_~ate; 


select 
• 
from 
0 r de r s 
order 
by 
order_date; 


select 
order_date, 
ship_date 
from 
0 r de r s 
order 
by 
customer 
num; 


In the first two statements, order_date is either explicitly or 
implicitly listed in the 8elect-list. 
In the third statement. even 
though customer_num is in the orders table. it is not in the 
select-list. 


select 
customer_num, 
fname, 
Iname, 
company 
from 
customer 
order 
by 
3, 
2; 


This statement performs a nested sort: the first level is the 
lname column; the second level is the fname column. 
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INTO TEMP Clause 


Overview 


Use the INTO TEMP clause to create a temporary table that 
contains the query results. The temporary table disappears 
when your program ends. 


Syntax 


INTO TEMP table-name 


Explanation 


INTO TEMP 
are required keywords. 


table-name 
is the RDSQL identifier you want to assign to 
the temporary table. 


Notes 


1. You save time if you use a temporary table when the same 
query results are required several times.. 


2. An INTO TEMP clause in a SELECT statement often gives 
you clearer and more easily understood statements. 


3. The column names of the temporary table are those named 
in the select-list. If you list a display label for a column or 
expression, the column name in the temporary table is the 
display label. 


4. There are no indexes associated with table-name. 


5. It is an error to use an INTO clause with the INTO TEMP 
clause. When you do, no results are returned to the host 
variables, and sqlca.sqlcode is set to a negative value. 
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6. The temporary table persists until you exit your Il'OFOR!\HX- 


ESQLlC program or issue the DROP TABLE statement for 
it. 
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UNION Operator 


Overview 


The UNION operator is a keyword placed between two 
SELECT statements that let you combine the queries into a 
single query. 


. Syntax 


SELECT-statement UNION [ALL] SELECT-statement 
[UNION [ALL] SELECT-statement ...] 


Explanation 


SELECT-statement 
is an RDSQL SELECT statement. 


UNION 


ALL 


Notes 


is a keyword that selects all rows from 
both queries, removes duplicates, and 
returns what is left. 


is an optional keyword that leaves the 
duplicates. 


1. The UNION operator can be placed between each member 
of a sequence of more than two queries. 


2. It is possible to write single queries that are equivalent to 
the compound queries constructed using the UNION opera- 
tor. The advantage of the UNION operator is that it makes 
the process easier. 


3. There are restrictions on the queries tht:.t you can connect 
with UNION operators. 
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• 
The number of the items in the select-list of each query 
must be the same, and corresponding items in each 
select-list must have identical data types. 


• 
Corresponding items need not have the same identifier. 


• 
Do not use an INTO statement in a query unless you are 
sure that the compound query will return exactly one 
row, and you are not using a cursor. In the case where 
you must do this when these conditions do not prevail, 
be sure that the INTO clause is in the first SELECT 
statement. 


• 
If you use an ORDER BY clause, it must follow the last 
SELECT statement, and you must refer by integer, not 
by identifier, to the item to be ordered. Ordering takes 
place after the set operation is complete. 


4. UNION operators must not occur inside a subquery and 
must not be used in the definition of a view. 


5. The column names (or display labels) of the resulting table 
are the same as those from the first SELECT statement. 


6. You can put the results of a UNION into a temporary table 
by putting an INTO TEMP clause in the final SELECT 
statement. 
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Examples 


The following statement selects those items (identified by· a 
stock number and a manufacturer code) that have a unit price 
of less than $100.00 or that have been ordered in quantities 
greater than three. 


select dist inct 
stock_num, 
manu_code 
from stock 
where 
uni t:.Jlr ice < 100.00 


union 


select 
stock_num, 
manu_code. 
from 
items 
where quant ity > 3 
order 
by 
1; 
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Aggregate and Date Functions 


You can use the aggregate and the date functions anywhere in 
an RDSQL expression that a constant appears. These functions 
are as follows: 


Aggregate 
Functions 


COUNT( ) 
SUM( ) 
AVG( ) 
MAX( ) 
MIN( ) 


Date 
Functions 


DATE( ) 
DAY( ) 
MDY( ) 
MONTH( ) 
WEEKDAY( ) 
YEAR( ) 


They are defined on the following pages: 
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Aggregate Functions 


Overview 


The aggregate functions take on values that depend on the set 
of rows returned by the WHERE clause of a SELECT 
statement. In the absence of a WHERE clause, the aggregate 
functions take on values that depend on all the rows formed by 
the FROM clause. 


Syntax 


COUNT(*) 


.COUNT(DISTINCT x) 


SUM([DISTINCT] x) 


AVG([DISTINCT] x) 


MAX(x) 
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Function 


returns the number of rows that 
satisfy the WHERE clause. 


returns the number of unique values 
in column x that satisfy the 
WHERE clause. 


returns the sum of all values in 
column x that satisfy the WHERE 
clause. You can apply SUM only to 
numeric columns. If you use the 
keyword DISTINCT, the sum is 
only over distinct values in 
column x. 


returns the average of all values in 
column x that satisfy the WHERE 
clause. You can apply AVG only to 
numeric columns. If you use the 
keyword DISTINCT, the average is 
only over distinct values in column 
x. 


returns the highest value contained 
in column x from a row that 
satisfies the WHERE clause. 


MIN(x) 


Notes 


returns the lowest value contained 
in column x from a row that 
satisfies the WHERE clause. 


1. In the functions SUM(x), AVG(x), MAX(x), and MIN(x), x 
can be an expression instead of a column. In this case, the 
function is evaluated over the values of the expression as 
computed for each row that satisfies the WHERE clause. 
Do not include another aggregate function in the expression. 


2. Use the DISTINCT keyword only with columns, not with 
expressions. 


3. In a select-list, use the keyword DISTINCT only once: 
either to eliminate duplicate query results or to eliminate 
duplicates from the argument of an aggregate function. 


4. NULL values affect the aggregate functions in the following 
ways: 


• 
COUNT(*) counts all rows, even if the value of every 
column in the row is NULL. 


• 
COUNT(DISTINCT x), AVG (x), SUM (x), MAX (x), 
and MIN (x) ignore rows with NULL values for x and 
return the appropriate values based on the rest of the 
rows. 


• 
If x contains only NULL values, then 
COUNT(DISTINCT x) returns zero, and the other four 
aggregate functions return NULL for that column. 
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DATEO 


Overview 


The DATE function returns a type DATE value corresponding 
to the expression with which you call it. 


Syntax 


DATE(expr) 


Explanation 


DATE 


expr 


Examples 


is a required keyword. 


is a required expression that can be converted 
to a type DATE value. 


The following statement uses DATE to convert a string 
tQ a date: 


. 
where end_date> date("12/13/1984") 


date(100) returns the 100th day after December 31, 1899. 
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DAYO 


Overview 


The DAY function returns the day of the month when you call 
it with a type DATE expression. 


Syntax 


DAY(date-expr} 


Explanation 


DAY 


date-expr 


is a required keyword. 


is a required expression of type DATE. 


DAYO 3-151 


MDYO 


Overview 


The MDY function returns a type DATE value when you call it 
with three expressions that evaluate to integers representing 
the month, date, and year. 


Syntax 


MDY(exprl, expr2, expr3) 


Explanation 


MDY 


exprl 


expr2 


expr3 


Notes 


is a required keyword. 


is an expression that evaluates to an integer 
representing the number of the month (1-12). 


is an expression that evaluates to an integer 
representing the number of the day of the 
month (1-28, 29, 30, or 31, depending on the 
month). 


is an expression that evaluates to a four-digit 
integer representing the year. 


1. The value of expr3 cannot be the abbreviation for the year 
because any two-digit integer is interpreted as in the first 
century. 
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MONTH() 


Overview 


The MONTH function returns an integer corresponding to its 
type DATE argument. 


Syntax 


MONTH(date-expr) 


Explanation 


I! 
MONTH 


date-expr 


is a required keyword. 


is a required expression of type DATE. 
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WEEKDAYO 


Overview 


The WEEKDAY function returns an integer that represents 
the day of the week when you call it with a type DATE 
expression. 


Syntax 


WEEKDAY(date-expr} 


Explanation 


WEEKDAY 


date-expr 


Notes 


is a required keyword. 


is a required expression of type DATE. 


1. WEEKDAY returns an integer in the range 0-6; 
orepresents Sunday, 1 represents Monday, and so on. 
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YEARO 


Overview 


The YEAR function returns an integer that represents the year 
when you call it with a type DATE expression. 


Syntax 


YEAR(date-expr) 


Explanation 


YEAR 


date-expr 


is a required keyword. 


is a required expression of type DATE. 
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Chapter Overview 


This chapter describes the data types used in RDSQL for 
columns in a database and how the data types are represented 
in the C language. In association with the RDSQL DATE and 
DECIMAL data types, it describes library functions for data 
conversion and manipulation. 


Correspondence Between RDSQL and C 


The following example lists the RDSQL data types and their 
C language counterparts. Use these to select the appropriate C 
data type for host variables corresponding to columns in the 
database. 


RDSQL Data Type 


CHAR(n) 


SMALLINT 
INTEGER 
SERIAL 
SMALLFLOAT 
FLOAT 
DATE 
MONEY 
DECIMAL 


C Data Type 


char array[n+l) 
string array[n+ 1) 
char * 
fixchar array[n] 
short int 
long int 
long int 
float 
double 
long int 
dec 
t or struct decimal 
dec=t or struct decimal 


The string andfixchar C data types are defined later in the 
section on the CHAR data type. 


See the section in this chapter on the DECIMAL data type for 
a full explanation of the DECIMAL data type and the dec_ t 
structure. 
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Within a C program using dynamically defined RDSQL 
statements, you can identify the data type returned to an sqlda 
structure by the DESCRIBE statement, by using the following 
constants defined in sqltypes.h: 


Constant 


SQLCHAR 
SQLSMINT 
SQLINT 
SQLFLOAT 
SQLSMFLOAT 
SQLDECIMAL 
SQLSERIAL 
SQLDATE 
SQLMONEY 


RDSQL Data Type 


CHAR 
SMALLINT 
INTEGER 
FLOAT 
SMALLFLOAT 
DECIMAL 
SERIAL 
DATE 
MONEY 


On small machines, both SQLFLOAT and SQLSMFLOAT 
correspond to DECIMAL. 


When you fill an sqlda structure to indicate where and what 
kind of host variables are used as input parameters to a 
dynamically defined RDSQL statement, you can use the following 
constants (also defined in sqltypes.h) to identify the C data 
type. 


Constant 


CCHARTYPE 
CSHORTTYPE 
CINTTYPE 
CLONGTYPE 
CFLOATTYPE 
CDOUBLETYPE 
CDECIMALTYPE 
CFIXCHARTYPE 
CSTRINGTYPE 
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C Data Type 


char 
short int 
int 
long 
float 
double 
struct decimal or dec 
t 
fixchar 
- 
string 


Data Conversion 


When there is a discrepancy between the data type of a 
database variable and that of the host variable, or between the 
data type of two columns, INFORMIX-ESQLlC attempts to convert 
one into the other. This includes the conversion of a CHAR 
type into a numeric type when the CHAR variable is a 
representation of a number. When a comparison is made 
between a CHAR value and a numeric value, for example, 
INFORMIX-ESQL/C converts the CHAR value to a numeric value. 
The conversion of a numeric type to a character type occurs 
through the creation of a string. RDSQL uses an exponential 
format for very large or very small numbers. 


If conversion is not possible, either because it makes no sense 
or because the receiving variable is too small to accept the con- 
verted value, INFORMIX-ESQL/C returns values as described in the 
following table, where "N" represents a numeric type and "C" a 
character type. 


Conversion 
Problem 
Result 


C-C 
does not fit 
String is truncated; 
sqlca.sqlwarn.sqlwarnl is 
set to W; indicator variable set 
to size of original string. 


N-C 
does not fit 
String is filled with asterisks; 
sqlca.sqlwarn.sqlwarnl 
is set to W; indicator variable 
is set to positive integer. 


C-N 
not number 
Number is undefined; 
sqlca.sqlcode is set to negative. 


C-N 
overflow 
Number is undefined; 
sqlca.sqlcode is negative. 


N-N 
overflow 
Number is undefined; 
sqlca.sqlcode is negative. 


RDSQL carries out all arithmetic in an arithmetic expression in 
type DECIMAL. The type of the resulting variable determines 
the format of the stored or printed result. The following rules 
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apply to the precision and scale of the DECIMAL variable that 
results from an arithmetic operation on two numbers: 


• 
All operands, if not already DECIMAL, are converted to 
DECIMAL, and the resulting number is DECIMAL. 


Convert Type 


FLOAT 
SMALLFLOAT 
INTEGER 
SMALLINT 


To 


DECIMAL(16) 
DECIMAL(8) 
DECIMAL(lO,O) 
DECIMAL(5,O) 


• 
The precision and scale of the result of an arithmetic opera- 
tion depend on the precision and scale of the operands and 
on the type of arithmetic expression. The rules are sum- 
marized in the example at the end of this section for arith- 
metic operations on operands with definite scale. When one 
of the operands has no scale (floating decimal), the result is 
a floating decimal. 


• 
If the operation is addition or subtraction, RDSQL adds trail- 
ing zeros to the operand with the smallest scale until the 
scales are equal. 


• 
If the type of the result of an arithmetic operation requires 
the loss of significant digits, RDSQL reports an error. 


• 
Leading or trailing zeros are not considered significant 
digits and do not contribute to the determination of 
precision and scale. 


In the following table, let p and s be the precision and scale of 
the first operand, and let p; and s; be the precision and scale of 
the second operand. 
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Operation 


Addition and 


Subtraction 


Precision and Scale of Result 


Precision: 
MIN(32, MAX(PI- Sl' P2- S2) 
+ MAX(sl' s2) + 1) 


Multiplication 
Precision: 


Scale 


MIN(32, PI+ P2) 


s + s 
1 
2 


Division 
Precision: 
32 


CHAR Type 


Scale: 
32 - P + s - s (cannot be negative) 
I 
I 
2 


The RDSQL CHAR data type is a character string whose length 
can vary from 1 to 32,767. When you associate a column with 
a CHAR data type in the CREATE TABLE statement, you 
must indicate its length with the notation CHAR(n). Within 
the data file, CHAR(n) is stored in n bytes. Because character 
strings in C are usually terminated with a null byte, you should 
declare the host array that receives a CHAR(n) value with a 
size of n + 1. 


If you choose to declare a host variable as a pointer to a char, 
be sure to allocate sufficient memory to receive the longest 
CHAR value. If you do not, you may overwrite other data 
when you transfer data from the database to your host variable. 


The INFORMIX-ESQLlC preprocessor recognizes two otherC data 
types for host variables: stringand fixchar. The char data 
type pads with trailing blanks up to the size of the CHAR 
column returned. It is null-terminated. The string data type 
differs from the char data type by truncating trailing blanks 
before inserting the null character to signal the end of the 
string. 
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The fixchar data· type is the same as the char except that it 
does not add the trailing null byte to terminate the string. 
This means that you can declare a fixchar host variable 
corresponding to a CHAR(n) column as an array with n 
components. 


SMALLINT and INTEGER Types 


SMALLINT and INTEGER are RDSQL data types that 
correspond to the C data types short and long. SMALLINT 
values can range from -32,767 to +32,767, while INTEGER 
values can range from -2,147,483,647 to +2,147,483,647. The 
values -32,768 for the SMALLINT and -2,147,483,648 for 
the INTEGER are reserved and cannot be used. Within a data 
file, the SMALLINT requires two bytes and the INTEGER 
four bytes. 
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SERIAL Type 


A SERIAL data type is a unique sequential integer assigned 
automatically by INFORMIX-ESQL/C when you execute an 
INSERT statement (see Chapter 2). The SERIAL data type 
corresponds to a long C type and occupies four bytes in a data 
file. When creating a table, you can indicate the starting 
number n (~ 1) for a SERIAL data type by declaring a column 
as SERIAL(n). 


SMALLFLOAT and FLOAT Types 


The SMALLFLOAT and FLOAT data types are implemented 
as float and double C data types, respectively. This means that 
they are binary floating-point numbers. You can experience 
round-off problems when they are expressed in decimal nota- 
tion. You may prefer to use the DECIMAL data type in place 
of SMALLFLOAT and FLOAT to avoid round-off. 


You can convert DECIMAL columns to float and double host 
variables to take advantage of the C mathematics library. You 
can also use float and double type host variables as input 
parameters in INFORMIX-ESQL/C statements. Since the range of 
allowed DECIMAL values is much larger than the range 
allowed to floats ordoubles, you should check that the magni- 
tude of the DECIMAL value is less than the maximum magni- 
tude for floats and doubles on your machine before making the 
conversion from DECIMAL to float or double. You can find 
functions that convert in both directions in the section on the 
DECIMAL.data types. 
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Small Machine Features: On small machines, RDSQL implements 
the SMALLFLOAT data type as DECIMAL(8) and FLOAT as 
DECIMAL(l6). In applications that use PERFORM on these machines 
(see Chapter 5), do not convert DECIMAL columns to float and 
double in your C programs. 


DATE Type 


INFORMIX-ESQL/C stores dates as a four-byte integer whose value 
is the number of days since December 31, 1899. Dates before 
December 31, 1899, are negative numbers while dates after 
December 31, 1899, are positive numbers. You can add and 
subtract numbers from DATE type values to produce a value 
corresponding to a date that many days later or earlier. You 
can also subtract two DATE types to get the number of days 
between them. 


Below are several date manipulation routines included in the 
libraries distributed with INFORMIX-ESQLlC for converting dates 
written in string form to and from this internal format. These 
are described on the next several pages. 


rdatestr 
rdayofweek 
rdefmtdate 
rfmtdate 
rjulmdy 
rleapyear 
rmdyjul 
rstrdate 
rtoday 
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Convert internal format to string 
Return day of week 
Convert string to internal format 
Convert internal format to string 
Return month, day, and year from internal format 
Determine whether leap year 
Return internal format from month, day, and year 
Convert string to internal format 
Return system date in internal format 


RDATESTR 


. Overview 


Use rdatestr to convert a date in internal format to a 
character string date of the form mm/dd/yyyy. 


Syntax 


rdatestr(jdate, str) 
long jdate; 
char *str; 


Explanation 


jdate 


str 


is the internal representation of a date as a long 
integer. 


is a pointer to the area where the results are to be 
stored. 
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RDAYOFWEEK 


Overview 


rdayofweek returns the day of the week represented as an 
integer, given an internal date as an argument. 


Syntax 


rdayofweek(jdate) 
long jdate; 


Explanation 


jdate 
is the internal representation of the date as a long 
integer. 


Return Values 


o Sunday 
1 
Monday 
2 
Tuesday 
3 
Wednesday 
4 
Thursday 
5 
Friday 
6 
Saturday 
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RDEFMTDATE 


Overview 


Use rdefmtdate to create a long integer whose value is the 
number of days since December 31, 1899, for a string date 
whose format is provided. 


Syntax 


rdefmtdate(jdate, fmtstring, input) 
long *jdate; 
char *fmtstring; 
char *input; 


Explanation 


jdate 
is a long integer, the internal representation of the 
date expressed as input. 


fmtstring 
is a pointer to a character array containing the 
format pattern for the date supplied in input. 


input 


Notes 


is a pointer to the string containing the date to be 
converted to a long integer. 


1. The string fmtstring uses the same formatting characters as 
rfmtdate. 


2. The input string and the fmtstring must be in the same 
sequential order in terms of month, day, and year. They 
.need not, however, have the same literals nor the same 
representation for month, day, and year. 
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Return Codes 


( 


o 


-1204 


-1205 


-1206 


-1209 


-1212 


Operation was successful. 


There is an invalid year component in the input 
parameter. 


There is an invalid month component in the input 
parameter. 


There is an invalid day component in the input 
parameter. 


Since *input does not contain delimiters between 
the year, month, and day components, the length of 
*input must be exactly six or eight bytes. 


fmtstring does not contain a year, a month, and a 
day component. 


Examples 


The following are valid combinations of fmtstring and input: 


fmtstring 


"mmddyy" 
"mmm. 
dd. 
yyyy" 
"mmm. 
dd. 
yyyy" 
"mmm. 
dd. 
yyyy" 
"mmm. 
dd. 
yyyy" 
"yy Imml dd" 
"yy Imml dd" 
"yy Imml dd" 


"dd...-mm-yy" 
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input 


"Dec. 
25th, 
1985" 
"dec 
25 
1985" 
"DEG-25-1985" 
"122585" 
"12/25/85" 
"85/12/25" 
"1985, 
December 
25th" 
"In 
the 
year 
1985. 
the month 
of 
December, 
its 
25th 
day" 
"This 
25th 
day 
of 
December. 
1985" 


RFMTDATE 


Overview 


Use rfmtdate to convert a date in internal format to a string 
formatted according to a pattern. 


Syntax 


rfmtdate(jdate, fmtstring, result) 
long jdate; 
char *fmtstring; 
char *result; 


Explanation 


jdate 
is the internal representation of a date as a long 
integer. 


fmtstring 
is a pointer to the character array containing the 
format pattern for the date returned in result. 


result 


Notes 


is a pointer to the character array that receives the 
formatted date. 


1. fmtstring consists of combinations of the characters m, d, 
and y shown in the following example. 
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dd 


ddd 


mm 
mmm 


yy 
yyyy 


Day of the month as a two-digit 
number (01-31) 
Day of the week as a three-letter 
abbreviation (Sun through Sat) 


Month as a two-digit number (01-12) 
Month as a three-letter abbreviation 
(Jan through Dec) 


Year as a two-digit number (00-99) 
Year as a four-digit number (0001-9999) 


2. Any other characters in fmtstring are reproduced literally in 
result. 


Return Codes 
o 


-1210 


-1211 
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The conversion was successful. 


The internal date cannot be converted to month- 
day-year format. 


Program has run out of memory-memory 
allocation error. 


Examples 


The examples that follow convert the integer jdate that 
corresponds to December 25, 1985, to a string result using the 
format in fmtstring. 


fmtstring 


"mmddyy" 
"ddmmyy" 
"yymmdd" 
"yy /mm/ dd" 
"yy 
mm dd" 


"yY-iTm-dd" 
"mmm. 
dd, 
yyyy" 
"mmm dd 
yyyy" 
"yyyy 
dd 
mm" 


"mmm. 
dd, 
yyyy" 
"ddd, 
mmm dd 
yyyy" 
"(ddd) 
mmm dd 
yyyy" 


result 


"122585" 
"251285" 
"851225" 
"85/12/25" 
"85 
12 25" 
"85-12-25" 
"Dec. 
25, 
1985" 
"Dec 
25 
1985" 
"1985 
25 
12" 
"Dec. 
25, 
1985" 
"Tue, 
Dec 
25 
1985" 
"(Tue) 
Dec 
25 
1985" 
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RJULMDY 


Overview 


rjulmdy creates an array of three short integers containing the 
month, day, and year components corresponding to an internal 
date. 


Syntax 


rjulmdy(jdate. mdy) 
long jdate; 
short mdy[3]; 


Explanation 


jdate 


mdy 


is the internal representation of the date as a long 
integer. 


is an array of short integers, where mdy[O] is the 
month (l to 12), mdy[l] is the day (l to 31), and 
mdy[2] is the year (l to 9999). 


Return Codes 
o 
The operation was successful. 
<0 
The operation failed. 
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RLEAPYEAR 


Overview 


rleapyear returns TRUE when the argument passed to it is a 
leap year and FALSE when it is not. 


Syntax 


rleapyear(year) 
int year; 


Explanation 


year 
is an integer. 


Notes 


1. The argument year must be the year component of a date 
and not the date itself. 


2. year must be expressed in full (1986) and not abbreviated 
(86). 


Return Codes 


TRUE(1) The year is a leap year. 
FALSE(O) The year is not a leap year. 
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RMDYJUL 


Overview 


Use rmdyjul to create an internal date from three short 
integers that contain the numeric values for the month, day, 
and year. 


Syntax 


rmdyjul (mdy, jdate) 
short mdy[3]; 
long *jdate; 


Explanation 


mdy 
is an array of short integers, where mdy[O) is the 
month (l to 12), mdy[1) is the day (l to 31), and 
mdy[2) is the year (l to 9999). 


jdate 
is a pointer to the internal representation of the 
returned date as a long integer. 


Notes 


1. The year must be expressed in full (1986) and not 
abbreviated (86). 


Return Codes 
o 
-1204 
-1205 
-1206 
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The operation was successful. 
There was an invalid year component in mdy[2). 
There was an invalid month component in mdy[O). 
There was an invalid day component in mdy[1). 


RSTRDATE 


Overview 


Use rstrdate to convert a character string date to a date in 
internal format. 


Syntax 


rstrdate(str, jdate) 
char *str; 
long *jdate; 


Explanation 


str 


jdate 


Notes 


is a pointer to the string to be converted. 


is a pointer to a long integer that receives the con- 
verted date. 


1. str should contain a numeric month, day, and year in that 
order. Any non-numeric character can be used as a 
separator between the month, day, and year. 


2. The year must be expressed in full (1986) and not 
abbreviated (86). 


Return Codes 


= 0 
The conversion was successful. 
< 0 
The conversion failed. 
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RTODAY 


Overview 


Use rtoday to put the system date into internal format. 


Syntax 


rtoday(today) 
long *today; 


Explanation 


today 
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is a pointer to a long integer that receives the 
current system date in internal format. 


MONEY Type 


A column with data type MONEY{m,n) is represented as a 
.DECIMAL type with a fixed precision m and a fixed number n 
of decimal places. A column declared as MONEY{m) is treated 
as DECIMAL{m, 2). A column declared as MONEY without 
precision or scale is treated as DECIMAL{l6, 2). Regardless of 
the number of parameters, MONEY type variables always have 
fixed-point arithmetic. See the following section, "DECIMAL 
Type," for further information. 


DECIMAL Type 


The data type DECIMAL is a machine-independent method 
for the representation of numbers of up to 32 significant digits, 
with or without a decimal point, and with exponents in the 
range -128 to +126. 


INFORMIX-ESQL/C provides routines that facilitate the conver- 
sion of DECIMAL type numbers to and from every data type 
allowed in the C Language. 


When you define a column as having the data type 
DECIMAL{m,n), it has a total of m (<= 32) significant digits 
(the precision) and n (< = m) digits to the right of the decimal 
point (the scale). When you give values for both m and n, the 
decimal variable has fixed-point arithmetic. All numbers less 
than 0.5 X lO-n in absolute value have the value zero. The 
largest absolute value of a variable of this type that can be 
stored without an error is lOm- n - 10-n. 


The second parameter is optional and, when missing, the 
variable is treated as a floating decimal. This means that 
DECIMAL{m) variables have a precision of m and a range in 
b 
I 
-128 
126 
a so ute value from 10 
to 10 
. When no parameters are 
designated, DECIMAL is treated as DECIMAL{l6), a floating 
decimal. 
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dec_exp; 
de c--'p os ; 
dec ndgts; 
dec dgts[DECSIZE]; 


DECIMAL type numbers consist of an exponent and a 
mantissa (or fractional part) in base 100. In normalized form, 
the first digit of the mantissa must be greater than zero. 


When used within a program, DECIMAL type numbers are 
stored in a C structure of the type shown below. 


#def ine DECSIZE 
16 


s t r uc t 
dec i rna I 
J 
Ishort 
s h° r t 
s h or t 
char 
I· 
I· 


typedef struct 
decimal 
dec_t; 


The decimal structure and the typedef dec_ t shown above 
are found in the header file decimal.h. Include this file in all 
C source files that use any of the decimal routines: 


#include <decimal.h> 


The decimal structure has four parts: 


dec_exp 


dec~os 


dec_ndgts 
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holds the exponent of the normalized 
DECIMAL type number. This exponent 
represents a power of 100. 


holds the sign of the DECIMAL type number 
(I when the number is zero or greater; 0 when 
less than zero). 


contains the number of base 100 significant 
digits of the. DECIMAL type number. 


is a character array that holds the significant 
digits of the normalized DECiMAL type 
number (dec 
dgts[O]! = 0). Each character 
in the array is a one-byte binary number in 
base 100. dec_ ndgts contains the number of 
significant digits in dec_ dgts. 


All operations on DECIMAL type numbers take place through 
the routines provided in INFORMIX-ESQL/C and described in the 
following section. Any other operations, modifications, or 
analyses can produce unpredictable results. 


DECIMAL Type Routines 


The following C function calls are available in INFORMIX-ESQLlC 
to treat DECIMAL type numbers: 


deccvaSc 
dectoasc 
deccvint 
dectoint 
deccvlong 
dectolong 
deccvdbl 
dectodbl 
decadd 
decsub 
decmul 
decdiv 
deccmp 
deccopy 
dececvt 
decfcvt 


Convert C char type to DECIMAL type 
Convert DECIMAL type to C char type 
Convert C int type to DECIMAL type 
Convert DECIMAL type to C int type 
Convert C long type to DECIMAL type 
Convert DECIMAL type to C long type 
Convert C double type to DECIMAL type 
Convert DECIMAL type to C double type 
Add two decimal numbers 
Subtract two decimal numbers 
Multiply two decimal numbers 
Divide two decimal numbers 
Compare two decimal numbers 
Copy a decimal number 
Convert decimal value to ASCII string 
Convert decimal value to ASCII string 
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DECCVASC 


Overview 


deccvasc converts a value held as printable characters in a C 
char type into a DECIMAL type number. 


Syntax 


deccvasc(cp,len,.np) 
char *cp; 
int len; 
dec_t *np; 


Explanation 


cp 
is a pointer to a string that holds the value to be 
converted. 


len 
is the length of the string. 


np 
is a pointer to the decimal structure where the result 
of the conversion is placed. 


Notes 


1. Leading spaces in the character string are ignored. 


2. The character string can have a leading sign, either + or -, 
a decimal point, and digits to the right of the decimal point. 


3. The character string may contain an exponent preceded by 
either e or E. The exponent can be preceded by a sign, 
either + or -. 
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Return Codes 
o 
-1200 


-1201 


-1213 
-1216 


Examples 


The conversion was successful. 
The number is too large to fit into a DECIMAL 
type (overflow). 
The number is too small to fit into a DECIMAL 
type (underflow). 
The string has non-numeric characters. 
The string has bad exponent. 


#include <decimal .h> 


c h a r 
I np u t [ 80]; 
dec_t 
n umbe r ; 


/ * 
get 
I nput 
from 
t e rmin a I 
* / 
get Ii ne( Input); 


/* 
convert 
input 
Into 
decimal 
number 
*/ 
deccvasc(lnput, 
32, 
&number); 


4-29 


DECTOASC 


Overview 


dectoasc converts a DECIMAL type number to a null- 
terminated printable ASCII string. 


Syntax 


dectoasc(np, cpo len, right) 
dec_t *np; 
char *cp; 
int 
len: 
int 
right; 


Explanation 


np 
is a pointer to the decimal structure whose 
associated decimal value is converted into an ASCII 
string. 


cp 
is a pointer to the beginning of the character buffer 
to hold the ASCII string. 


len 
is the maximum length in bytes o'f the string buffer, 


right 
is an integer indicating the number of decimal 
places to the right of the decimal point. 


Notes 


1. If right = -1, the number of decimal places is determined 
by the decimal value of *np. 
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2. If the number does not fit into a character string of length 
len, dectoasc converts the number to an exponential nota- 
tion. If the number still does not fit, the string is filled with 
asterisks. If the number is shorter than the string, it is left 
justified and padded on the right with blanks. 


Return Codes 
o 
The conversion was successful. 
- 1 
The conversion failed. 


Examples 


#include <decimal .h> 


char 
input[80]; 
char 
output[16]; 
dec_t 
n umbe r ; 


j* 
get 
input 
from 
terminal 
*j 
getl i nee input); 


j* 
convert 
input 
into 
decimal 
number 
*j 
deccvasc(input, 
32, 
&number); 


j* 
convert 
number 
to printable string 
*j 
dectoasc(&number, 
output, 
16, 
1); 


j* 
print 
the 
value 
just 
entered 
*j 
p r i n t f ("You 
jus te n t ere d %stI , 
output); 
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DECCVINT 


Overview 


Use d€~cvint to convert a C type int into a DECIMAL type 
number. 


Syntax 


deccvint(integer, np) 
int integer; 
dec_t *np; 


Explanation 


integer 


np 


Examples 


is the integer to be converted. 


is a pointer to a decimal structure where the result 
is placed. 


#include <decimal .h> 


/ * con ve r t 
the 
i n t e 9e r val ue -999 
* into a DECIMAL type number 
* / 
deccvint(-999, 
&decnum); 
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DECTOINT 


Overview 


Use dectoint to convert a DECIMAL type number into a C 
type into 


Syntax 


dectoint(np, ip) 
dec_t *np; 
int *ip; 


Explanation 


np 
is a pointer to a decimal structure whose value is 
converted to an integer. 


Lp 
is a pointer to the integer. 


Return Codes 
o 


-1200 


The conversion was successful. 


The magnitude of the DECIMAL type number > 
32767. 
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Examples 


#include <decimal .h> 


dec_t mydecimal; 
int 
myinteger; 


/* convert 
the value 
in 
* my dec irna lin t 0 ani n t e 9e r 
* and place the results 
in 
* the variable myinteger. 
* / 
dectoint(&mydecimal. 
&myinteger); 
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DECCVLONG 


Overview 


Use deccvlong to convert a C type long value into a 
DECIMAL type number. 


Syntax 


deccvlong(lng, np) 
long Ing; 
dec_t *np; 


Explanation 


Lng 
is the long value that is converted into a DECIMAL 
type value. 


np 
is a pointer to a decimal structure that holds the 
DECIMAL type number. 


4-35 


Examples 


#include <decimal .h> 


dec_t 
mydec ima I; 
long 
mylong; 


/* 
Set 
the 
decimal 
structure 


* mydec ima I 
to 
37. 


* / 
deccvlong(37L, 
&mydecimal); 


mylong = 
123456L; 
/* 
Convert 
the 
variable mylong 
into 


* 
a 
DECIMAL 
type 
number 
held 
in 


* 
mydec ima I. 


* / 
deccvlong(mylong, 
&mydecimal); 
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DECTOLONG 


Overview 


Use dectolong to convert a DECIMAL type number into a 
long. 


Syntax 


dectolong(np,lngp) 
dec_t *np; 
long *lngp; 


Explanation 


np 
is a pointer to a decimal structure. 


lngp 
is a pointer to a long integer where the result of the 
conversion is placed. 


Return Codes 
o 


-1200 


The conversion was successful. 


The magnitude of the DECIMAL type number > 
2,147,483,647. 
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Examples 


#include <decimal .h> 


dec_t 
mydec i ma I ; 
long 
mylong; 


/* 
convert 
the 
DECIMAL 
type 
value 


* 
he I din 
the 
dec i ma 1st r u c t u r e 


* mydecimal 
to 
a 
long pointed 
to 


* 
by mylong. 


* / 
dec t 0 Ion g ( amy dec i ma I, 
amy Ion g) ; 
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DECCVDBL 


Overview 


Use deccvdbl to convert a C type double into a DECIMAL 
type number. 


Syntax 


deccvdbl(dbI, np) 
double dbl; 
dec_t *np; 


Explanation 


dbl 
is the double value that is converted into a 
DECIMAL type value. 


np 
is a decimal structure that contains the DECIMAL 
type number. 
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Examples 


#include <decimal .h> 


dec_t 
mydec i ma I ; 
double 
mydouble; 


/. 
Set 
the 
decimal 
structure 
• 
mydecimal 
to 
3.14159 . 
./ 
dec c v d b I (3 . 14 159, 
&my dec i ma I ) ; 


mydouble = 
123456.78; 


• 
Convert 
the 
variable mydouble 
into 
• 
a 
DECIMAL 
type 
number 
held 
in 
• 
mydec ima I. 


• J 
deccvdbl (mydouble, 
&mydecimal); 
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DECTODBL 


Overview 


Use dectodbl to convert a DECIMAL type number into a 
double. 


Syntax 


dectodbl(np, dblp) 
dec_t *np; 
double *dblp; 


Explanation 


np 
is a pointer to a decimal structure. 


dblp 
is a pointer to a double where the result of the 
conversion is placed. 


Notes 


1. Depending upon the floating-point format of the host 
machine, the conversion of a DECIMAL type number to a 
double can result in the loss of precision. 
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Examples 


#include <decimal .h> 


dec_t 
mydec ima I; 
double mydouble; 


/* convert 
the 
DECIMAL 
type value 
• 
he Idin 
the dec ima 1st r uc t u r e 
* mydecimal 
to 
a double pointed 
to 
* 
by mydouble. 
* / 
dectodbl (&mydecimal, 
&mydouble); 
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DECADD, DECSUB, DECMUL, and DECDIV 


Overview 


The decimal arithmetic routines take pointers to three decimal 
structures as parameters. The first two decimal structures hold 
the operands of the arithmetic function. The third decimal 
structure is where the result is placed. 


Syntax 


decadd(nl, n2, result) 
dec_t *nl; 
dec_t *n2; 
dec 
t *result: 


decsub(nl, n2, result) 
dec_t*nl; 
dec_t *n2; 
dec_t *result; 


decmul(nl, n2, result) 
dec 
t *nl' 
dec-t *n2: 
dec_t *re~ult; 


decdiv(nl, n2, result) 
dec 
t *nl' 
dec-t *n2: 
- 
, 
dec_t *result; 


Explanation 


/* result = nl + n2 */ 


/* result = nl - 
n2 */ 


/* result = nl * n2 */ 


/* result = nl / n2 */ 


nl 


n2 


result 


is a pointer to the decimal structure of the first 
operand. 


is a pointer to the decimal structure of the second 
operand. 


is a pointer to the decimal structure of the result of 
the operation. 
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Notes 


1. result can be the same as either nl or n2. 


Return Codes 
o 
-1200 
-1201 
-1202 


The operation was successful. 
The operation resulted in overflow. 
The operation resulted in underflow. 
The operation attempted to divide by zero. 
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DECCMP 


Overview 


Use deccmp to compare two DECIMAL type numbers. 


Syntax 


int deccmpinl, n2) 
dec 
t *nl; 
dec-t *n2; 


Explanation 


nl 
is a pointer to the decimal structure of the first 
number. 


n2 
is a pointer to the decimal structure of the second 
number. 


Return Codes 


- 1 The first value is less than the second. 
o The two values are the same. 
1 The first value is greater than the second. 
DECUNKNOWN Either value is NULL. 
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DECCOPY 


Overview 


Use deccopy to copy one decimal structure to another. 


Syntax 


deccopy(nl, n2) 
°dec_t *nl; 
dec_t *n2; 


Explanation 


nl 
is a pointer to the value held in the source decimal 
structure. 


n2 
is a pointer to the destination decimal structure. 
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DECECVT and DECFCVT 


Overview 


These decimal routines are analogous to the subroutines under 
ECVT(3) in section three of the UNIX Programmer's Manual. 
dececvt works in the same fashion as ecvt(3), and decfcvt 
works in the same fashion as fcvt(3). They both convert a 
decimal value to an ASCII string. 


Syntax 


char *dececvt(np, ndigit, decpt, sign) 
dec_t *np; 
int ndigit; 
int *decpt; 
int *sign; 


char *decfcvt(np, ndigit, decpt, sign) 
dec_t *np; 
int ndigit; 
int *decpt; 
int *sign; 


Explanation 


np 


ndigit 


decpt 


sign 


is a pointer to a decimal-structure containing the 
decimal value to be converted. 


is, for dececvt, the length of the ASCII string. For 
decfcvt, it is the number of digits to the right of the 
decimal point. 


is a pointer to an integer that is the position of the 
decimal point relative to the beginning of the string. 
A negative value for *decpt means to the left of the 
returned digits. 


is a pointer to the sign of the result. If the sign of 
the result is negative, *sign is nonzero; otherwise, it 
is zero. 
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Notes 


1. dececvt converts the decimal value pointed to by np into a 
null-terminated string of ndigit ASCII digits and returns a 
pointer to the string. 


2. The low~order digit is rounded. 


3. decfcvt is identical to dececvt, except that ndigit specifies 
the number of digits to the right of the decimal point 
instead of the total number of digits. 


Examples 


Let np point to 12345.67 and suppress all arguments except 
ndigit: 


deeeevt (4) 
deeeevt (10) 
deefevt(1) 
deefevt(3) 


"1235" 
"1234567000" 
"123457" 
"12345670" 


-deept 
-deept 
-deept 
-deept 


5 
5 
5 
5 


Now let np point to.001234: 
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deeeevt (4) 
deeeevt(10) 
deefevt(1) 
deefevt(3) 


"1234" 
"1234000000" 
"""1'" 


-deept =-2 
-deept 
= -2 
-deept 
= -2 
-deept 
= -2 


Chapter 5 


Library Functions 


5-2 


Chapter 5 Table of Contents 


Chapter Overviev,' 
5 


Function Descriptions 
5 
BYCMPR..................................................................................... 
6 


BYCOPy' 
8 
B"i 
7FILL........................................................................................ 
9 
By·LENG...................................................................................... 
10 
LDC·HAR...................................................................................... 
11 
RDO\VNSHIFT 
12 
RISNULL..................................................................................... 
13 
RSETNULL................................................................................. 
14 
RSTOD......................................................................................... 
15 
RSTOI 
16 
RSTOL......................................................................................... 
17 
RTYPALIGN............................................................................... 
18 
RTYPMSIZE 
19 
RTYPNAME 
20 
RTYPWIDTH 
21 
RUPSHIFT 
22 
STCAT 
23 
STCMPR...................................................................................... 
24 
STCHAR...................................................................................... 
25 
STCOPY....................................................................................... 
26 
STLENG 
27 


5-3 


ii-4 


Chapter Overview 


This chapter describes the RDS library functions included with 
I1'OFORMIX-ESQLlC. Use these functions in your C programs. 
When you use a compiler shell script (esqI, cace, or cperf), 
these functions are linked automatically to your program. 


Function Descriptions 


The RDS library extension comprises the routines listed below. 
Those beginning with by act on and return fixed-length strings 
of bytes. Those beginning with rst and st (except stchar) 
operate on and return null-terminated strings. 


bycmpr 
bycopy 
byfill 
byleng 
ldchar 
rdownshift 
risnull 
rsetnull 
rstod 
rstoi 
rstol 
rtypalign 
rtypmsize 
rtypname 
rtypwidth 
rupshift 
stcat 
stcmpr 
stchar 
stcopy 
stleng 


Compare two groups of contiguous bytes 
Copy bytes from one area to another 
FiJI specified area with a character 
Count number of bytes in string 
Copy fixed-length string to null-terminated string 
Convert all letters to lowercase 
Check if C variable is null 
Set a C variable to null 
Convert string to double 
Convert string to short 
Convert string to long 
Align data on proper type boundary 
Give byte size of RDSQL data types 
Convert data type to string 
Give minimum conversion byte size 
Convert all letters to uppercase 
Concatenate one string to another 
Compare two strings 
Copy null-terminated string to fixed-length string 
Copy string to another string 
Count number of bytes in string 
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BYCMPR 


Overview 


The bycmpr function compare~ two groups of contigulHb 
b~·te;; 


for a gi\'en length. returning the results of the comparisoJ] as 
the \'alue of the function. 


Syntax 


h~"("mprlh~'1(·l. h\'1(-:2, length I 
('har *h\"I('I: 
('har 
*b~'le:!: 


inl len}.,'! h: 


Explanation 


hyt('] 


hytc:2 


lengt h 


Notes 


is a pointer to the starting location of tl1(-' first grclUp 
of cont iguous byt es. 


is a pointer to the starting location of the St'l'llnd 
group of contiguous bytes, 


is the number of bytes o\'er which the comparison 
occurs, 


1. 
81./1/('11 is only used for character data 
t~·I)E:'s. when- tl1(-' 


length is not predetermined. 


.) 
bycmpr performs a b~·te-by-byte comparison of the t\\"<l 
groups of contiguous bytes until a difference is found and 
returns an integer whose sign is the same as that of the 
difference between the two differing bytes. 


.'i-G 
Fun('1 i"n 
De~('fipli()n~ 


;~. 
The bytes of the byt£'2 group are subtracted from those of 
the byt£' J group. 


Return Codes 
= 0 
The t",'o groups are identical. 
<0 
byte J group < byte2 group. 
>0 
byte1 group> byte2 group. 


5-7 


BYCOPY 


Overview 


The bycopy function copies a gi\"en number of bytes from one 
locat ion to another. 


Syntax 


bycopy(frOln. to. ltongthl 


char 'from: 
char 'to: 
int length: 


Explanation 


from 


to 


length 


Notes 


is a pointer to the starting byte of the 
group of bytes to be copied. 


is a pointer to the starting byte of the destinat ion 
group of bytes. 


is the number of bytes to be copied. 


1. Take care not to overwrite areas of memory adjacent to the 
area to be copied. 
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BYFILL 


Overview 


The byfill function fills a specified area with one character. 


Syntax 


h~·fill(to. length. ch) 
char 'to: 
int leng1 h: 
char ch: 


Explanation 


t{) 


length 


('h 


Notes 


is the starting byte of the memory area to be filled. 


is the number of times the character is repeated 
within the area. 


is the character that fills the area. 


1. Take care not to overwrite areas of memory adjacent to the 
area to be copied. 
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BYLENG 


Overview 


The byleng function returns the number of significant 
characters in a string, not counting trailing blanks. 


Syntax 


byleng( from. count) 
char *from: 
int count: 


Explanation 


from 


count 


is pointer to a fixed-length string (not null- 
terminated). 


is the number of bytes in the fixed-length string. 
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LDCHAR 


Overview 


The ldchar function- copies a fixed-length string into a null- 
terminated string with any trailing blanks removed. 


Syntax 


ldchar(from. count. t()) 
char *from: 
char *to: 
int count: 


Explanation 


from 


count 


to 


is a pointer to the fixed-length source string. 


is the number of bytes in the fixed-length source 
string. 


is a pointer to the first byte of a null-terminated 
destination string. 
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RDOWNSHIFT 


Overview 


The rdownshift function changes all of the characters within 
a null-terminated string to lowercase. 


Syntax 


rdownshiftls) 
char '5; 


Explanation 


s 
is a pointer to a null-terminated string. 
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RISNULL 


Overview 


The risnull function checks whether a C variable is null. 


Syntax 


risnu!Htype, ptrvar) 
int t.ype; 
char *ptrvar; 


Explanation 


type 


ptrL'ar 


is an integer corresponding to the data type of 
a C variable (see Chapter 4). 


is a pointer to the C variable. 


Return Codes 


1 
The variable is null. 
o 
The variable is not null. 
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RSETNULL 


Overview 


The rsetnull function sets a C variable to a value that 
corresponds to a database NULL value. 


Syntax 


rsetnu!Htype. ptvar) 
int type; 
char *ptrvar; 


Explanation 


type 


ptrvar 


5-14 Function Descriptions 


is an integer corresponding to the data type of 
a C variable (see Chapter 4). 


is a pointer to the C variable. 


RSTOD 


Overview 


The rstod function converts a null-terminated string into a 
double. 


Syntax 


rsl odl 0"1 ring. double__va]) 


('har *slring: 
douhle *douhle 
val: 


Explanation 


."tring 


double 
L'al 


Return Codes 


is a pointer to a null-terminated string. 


is a pointer to a double where the result of the 
function is held. 


= 0 
The conversion was successful. 


~ = 0 
The conversion failed. 
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RSTOI 


Overview 


The rstoi function converts a null-terminated string into a 
integer. 


Syntax 


rstoi(string. ivaI) 
char *string; 
int *ival: 


Explanation 


string 


ival 


Notes 


isa pointer to a null-terminated string. 


is a pointer to a integer where the result of the 
function is held. 


1. The legal range of values is from -32767 to 32767. 


2. If string corresponds to a NULL integer, ival points to the 
representation for a SMALLINT NULL. If you want to 
convert a string that corresponds to a long integer, use 
rstol. Failure to do so can result in corrupt data 
representation. 


Return Codes 


=0 
The conversion was successful. 


!= 0 
The conversion failed. 
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RSTOL 


Overview 


The rstol function converts a null-terminated string into a long 
integer. 


Syntax 


rst oj(string. ]ong_)ntl 
char *string; 
long *Iong_int; 


Explanation 


string 
is a pointer to a null-terminated string. 


{ong_int 
is a pointer to a long integer where the result of the 
function is held. 


Notes 


1. The legal range of values is from <-2,147,483,647 to 
2.147.483,647. 


Return Codes 
= 0 
The conversion was successful. 


~ = 0 
The conversion failed. 


5-17 


RTYPALIGN 


Overview 


The rtypalign function returns the position of the next proper 
boundary for a variable of the specified data type. 


Syntax 


rtypalign (pas. type) 
int pas; 
int type; 


Explanation 


pas 
is the current position in a buffer. 


type 
is the integer code for a C or RDSQL data type. 


Notes 


1. rtypalign and rtypmsize are useful when setting up an 
sqlda to FETCH data into a buffer. 


2. The value of type is returned by DESCRIBE into 
sqlda.sqlvar->sqltype. 


Return Codes 


n (>0) 
The offset of the next word boundary. 
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RTYPMSIZE 


Overview 


The rtypmsize function returns the number of bytes you must 
allocate in memory for the specified C or RDSQL type. 


Syntax 


rtypmsize (sqltype, sqllen) 
int sqltype; 
int sqllen; 


Explanation 


sqltype 


sqllen 


Notes 


is the integer code of the C or RD8QL type. 


is the number of bytes in the data file for the 
specified RDSQL type. 


1. rtypmsize is designed to be used with the sqlda structure 
returned by a DESCRIBE statement. sqltype and sqllen 
correspond to the components of the same name in each 
sqlda.sqlvar structure. 


2. For CCHARTYPE and CSTRINGTYPE, rtypmsize adds 
one byte to the number of characters for the null termina- 
tor. For CFIXCHARTYPE, there is no null terminator. 


Return Codes 


o 
n (>0) 
sqltype is not a valid RDSQL type. 
The number of bytes required for data type is n. 
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RTYPNAME 


Overview 


The rtypname function returns a null-terminated string 
containing the name of the specified RDSQL type. 


Syntax 


char *rtypname (sqltype) 
int sqltype 


Explanation 


sqltype 
is an integer code for one of the RDSQL types. 


Return Codes 


The following values are returned: 


sqltype 


SQLCHAR 
SQLSMINT 
SQLINT 
SQLFLOAT 
SQLSMFLOAT 
SQLDECIMAL 
SQLSERIAL 
SQLDATE 
SQLMONEY 
invalid type 
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return string 


"char" 
"smallint" 
"integer" 
"float" 
..smallftoat" 
"decimal" 
"serial" 
"date" 
"money" 
.... (null string) 


RTYPWIDTH 


Overview 


The rtypwidth function returns the minimum number of 
characters required to avoid truncation when converting a value 
with a RDSQL type to a character data type. 


Syntax 


rtypwidth (sqltype, sqllen) 
int sqltype; 
int sqllen: 


Explanation 


sqltype 


sqllen 


Notes 


is the integer code of the RDSQL type. 


is the number of bytes in the data file for the 
specified RDSQL type. 


1. rtypwidth is designed to be used with the sqlda structure 
that is returned by a DESCRIBE statement. sqltype and 
sqllen correspond to the components of the same name in 
each sqlda.sqlvar structure. 


Return Codes 


o 


n (> 0) 


sqltype is not a valid RDSQL type. 


A value of type sqltype requires a minimum of n 
characters to be expressed. 
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RUPSHIFT 


Overview 


The rupshift function changes all of the characters within a 
null-terminated string to uppercase. 


Syntax 


rupshift(s) 


char *s: 


Explanation 


s 
is a pointer to a null-terminated string. 


5-22 Function Descriptions 


STCAT 


Overview 


The stcat function concatenates one null-terminated string to 
the end of another. 


Syntax 


stcat(s, destl 
char *s, *dest; 


Explanation 


s 
is a pointer to the start of the string that is placed 
at the end of the destination string. 


dest 
is a pointer to the start of the null-terminated 
destination string. 
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STCMPR 


Overview 


The stcmpr routine compares two null-terminated strings. 


Syntax 


stcmpr(sl, s2) 
char *sl, *s2; 


Explanation 


81 
is a pointer to the first null-terminated string. 


82 
is a pointer to the second null-terminated string. 


Notes 


1. 
81 is greater than 82 when 81 appears after 82 in the ASCII 
collating sequence. 


Return Codes 
= 0 
The two strings are identical. 
<0 
The first string is less than the second. 
>0 
The first string is greater than the second. 
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STCHAR 


Overview 


The stchar function stores a null-terminated string in a fixed- 
length string. padding the end with blanks if necessary. 


Syntax 


stchar(from. to. count) 
char *from: 
char *to: 
int count: 


Explanation 


from 


to 


count 


is a pointer to the first bJie of a null-terminated 
source string. 


is a pointer to the fixed-length destination string. 


is the number of bytes in the fixed-length 
destination string. 
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STCOPY 


Overview 


The stcopy function copies a null-terminated string from one 
location in memory to another location. 


Syntax 


stcopy(from. to) 
char *from, *to; 


Explanation 


from 
is a pointer to the null-terminated string to be 
copied. 


to 
is a pointer to a location in memory where the 
string is copied. 
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STLENG 


Overview 


The stleng function returns the length. in bytes. of a specified 
null-terminated string. 


Syntax 


st leng( st ring) 


char *string: 


Explanation 


,.;;tring 


Notes 


is a pointer to a null-terminated string. 


1. The length does not include the terminating null. 
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Chapter Overview 


This chapter discusses interfacing C language routines with 


I~FORl\nX-SQL. If you have only INFORMIX-ESQLlC. this chapter 
is not relevant and can be skipped. 


The ACE Report Writer and the PERFORM Screen Transaction 
Processor are the powerful report writing and interactive screen 
form processor programs of the RDS relational database 
management system, INFORMIX-SQL. Each of these programs 
uses a program (ACEPREP for ACE and FORMBLILD for PERFORM) 
to compile a user-created specification file that describes the 
customized report or screen form. This chapter supplements 
the material in the INFORMIX-SQL User Manual by describ- 
ing how you can call C functions from the specification file for 
both ACE and PERFORM. If your application uses PERFORM, this 
chapter assumes you are familiar with the material in Chapters 
3 and 4 of the INFORMIX-SQL Reference Manual. If your 
application uses ACE, it is assumed that you are familiar with 
Chapter 5 of the INFORMIX-SQL Reference Manual. 


While both ACE and PERFORM can usually handle all your 
database reports and screen interactions without modification, 
occasionally you may find it necessary to add a feature that is 
not present. For example, a C function called from ACE might 
make statistical computations on the data presented in a report 
and add these to the report. PERFORM might call C functions to 
check on the validity of data,to record the date, time, and 
name of the person updating the records, as well as to edit and 
to update the database. C functions can use library routines 
described in Chapter 4, "RDSQL Data Types" and Chapter 5, 
"Library Functions" (and for PERFORM, the special functions at 
the end of this chapter), contain INFORMIX-ESQLlC statements, 
and call math functions or other C subroutines. Your ability to 
call user-defined C functions increases the power and flexibility 
of ACE and PERFORM. 


This chapter discusses how to call a C function from within the 
specification files for ACEPREP and FORMBUILD, how to con- 
struct the C function, and how to create custom versions of ACE 
and PERFORM containing your C function(s). 
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ACE Report Specification Files 


The general format of an ACE report specification file has six 
sections: 


DATABASE section (required) 
DEFI:t\E section 
I:t\PUT section 
OUTPl.1T section 
SELECT section (required) 
FORMAT section (required) 


You call a C function from within a report specification file 
b~' 


declaring the function name in the DEFINE section and by 
using the function in the FORMAT section. Then use ACEPREP 
to compile the report specification file. 


Declaring C Functions 


You declare a C function in the DEFINE section of the report 
specification file. 


Syntax 


DEFI:t\E 
Fl1NCTION user!unc 


END 


Explanation 


DEFINE 


FUNCTION 


is a required keyword. 


is a required keyword. 
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u8crfunc 


END 


Notes 


is the name by which the C function is 
referenced in the specification file. 
userfunc 
must satisfy the conditions for an ACE 
identifier. 


is a required keyword. 


1. You can declare several functions at the same time by 
repeating the keyword FUNCTION followed by the next. 
function name. 


2. 
Do not include parentheses after the function name. 


:3. You can have PARAM and VARIABLE statement.s within 
the DEFINE section in addition t.o the FUNCTION 
statement. 


Calling C Functions 


The FORl'vlAT section of the report specification file contains 
one or more control blocks that determine when ACE will take 
an action. 


FOR!\L\T 


PAGE HEADER control block 
PAGE TRAILER control block 
FIRST PAGE HEADER control block 
01\ E\'ERY RO\\' control block 
O!\ LAST RO\\' control block 
BEFORE GROLTP OF control block 
AFTER GROep OF control block 


E!\D 
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Each control block contains one or more statements that tell 
ACE what action to take. Chapter 5 of the INFORMIX-SQL 
Reference Manual describes a variety of statements that ACE 
allows. In addition to the statements defined there, you can 
use a C function call. 


[CALL] userfunc( [expr-list]) 


Explanation 


CALL 


userfunc 


expr-list 


Notes 


is an optional keyword that must be used when 
the C function does not return a value. When 
CALL is missing, userfunc must return a value. 


is the name of a C function that has been 
previously declared in the DEFINE section. 


is one to ten expressions separated by commas. 


1. An expression can be anything from a simple numeric or 
alphabetic constant to a more complex series of column 
names, ACE variables, ACE parameters, ACE functions (such 
as group aggregates and date functions), quoted strings, 
arithmetic and logical operators, and keywords. 


2. 
ACE statements are composed of keywords and expressions. 
You can also use a C function in an expression where you 
can use a constant. In this case, do not include the CALL 
keyword, and the C function must return a value. 
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Examples 


after 
group 
of 
order_num 
call 
stat(order_num) 


This control block calls a C function stat that calculates 
statistics on the data in the rows that correspond to the order 
number = order 
num. 


on 
eve r y 
row 
pr i nt 
order_num, 
logarithm((total 
of 
total-'price);(today 
- 
order_date» 


This control block prints the name and a value intended to 
correlate the total price of each order with the period of time 
the order has been outstanding. It calls a C function that 
computes the logarithm. 


first 
page 
header 
call 
to_unix(ndaten ) 


This control block is taken from Example 2 at the end of this 
chapter. At the top of the first page of the report it prints the 
system date and time. The function to_unix sends its string 
argument to the UNIX operating system. 


Compiling the Report Specification 


Use ACEPREP to compile the report specification when there are 
C function calls in the same manner as when there are none. 
Give the report specification file a filename with the extension 
.ace, as in spectile.ace. To use ACEPREP, enter the following 
statement on the command line. 


saceprep specfile 


See Chapter 5 of the INFORMIX-SQL Reference Manual for 
further details. 
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PERFORM Form Specification Files 


The general format of a PERFOR~f form specification file has 
five sections: 


DATABASE section (required) 
SCREE!\' section (required) 
TABLES section (required) 
ATTRIBUTES section (required) 
INSTRUCTIONS section 


You can use C functions in the control blocks in the 
INSTRUCTIONS section of a form specification file. 


Calling the C Function 


In control blocks, you can use C functions anywhere you can 
use an expression, or they can stand alone as the most general 
action. The syntax for a call to a user-defined function is as 
follows: 


Syntax 


[CALL] userfund [expr-list]) 


Explanation 


CALL 
is an optional keyword that must be used when the 
C function does not return a value. When CALL is 
missing, userfunc must return a value. 


userfunc 
is the name by which the C function is referenced in 
the PERFORM specification. 
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expr-list 
is a list of zero to ten expressions. An expression is 
defined as 


• 
a field tag 


• 
a constant value 


• 
an aggregate value 


• 
a C function 


• 
the keyword TODAY 


• 
any combination of the above, combined by using 
the arithmetic operators +, -, *, and / 


For more information about the LET and IF-THEN-ELSE 
actions and expressions, refer to the INFORMIX-SQL 
Reference Manual, Chapter 3. 


Examples 


after editadd of 
proj_num 
let 
f001 = userfunc(f002) 


before editupdate of 
paid_date 
if 
boolfunc(f003) 
then 
let 
f004 
15 
else 
let 
f004 
10 


after 
add update 
remove of 
customer 
call 
userfunc() 
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ON BEGINNING and ON ENDING 


ON BEGINNING and ON ENDING are two control blocks 
that can be used only with calls to C functions. These control 
blocks are specified in the INSTRUCTIONS section of the 
form specification file. ON BEGINNING executes immediately 
after PERFORM is invoked, and ON ENDING executes immedi- 
ately after the EXIT command. By using ON BEGINNING, 
you can give instructions, request a special password, or initial- 
ize a temporary workfile in which to keep a batch of transac- 
tion records. By using ON ENDING, you can perform calcula- 
tions to summarize the changes made in the database during 
the PERFORM session that just concluded, print summaries of 
the records added, or erase workfiles. 


You can have more than one ON BEGINNING and/or ON 
ENDING control block in the INSTRUCTIONS section. 
However, you can have only one CALL statement in each 
control block. 


Syntax 


ON BEGINNING 
CALL userfunc(expr-list) 


ON ENDING 
CALL userfunc(expr-list) 


The explanation of the syntax is identical to that in the 
preceding section. 
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Compiling the Form Specification 


Use FORMBUILD to compile the form specification file when 
there are C function calls in the same manner as when there 
are none. Give the form specification file a filename with the 
extension .per, as in specfile.per. To use FORMBUILD, enter the 
following statement on the command line. 


sformbld specfile 


See Chapter 3 of the INFORMIX-SQL Reference Manual for 
further details. 
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Writing the C Program 


If you make reference to C functions within an ACE report 
specification file or a PERFORM form specification file. you must 
create a custom version of ACE or PERFOR:\f that knows the 
functions. You must write a C program that includes the 
appropriate header files and structure declarations. as well as 
your functions. You then must compile and link your program 
to the appropriate libraries. This section shows you how to 
organize your C program. how to declare your functions, and 
how to pass \'alues to and from your functions. 


C Program Structure 


To create a version of ACE or PERFORM that includes your 
functions, you must write a C program that contains the 
appropriate declarations. Your program can have one or more 
functions, and you can define other functions to use internally 
in your program. The following display shows the general 
structure of such Ii C program that includes t\\'O user-defined 
functions: 
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~include "ctools.h" 
j" 
add 
other. includes 
as desi red" 


valueptr 
lunct1(); 
valueptr 
lunct2(); 


struct 
ulunc userluncs 


"my I un c t 1" , 
"mylunct2", 
0,0 
, ., , 


I un c t 1 , 
I un c t 2 , 


," 
add other global 
declarations 
"j 


valuept r 
lunct1() 


j" 
lunct1 
takes 
no arguments 
and 
returns 
a character 
string 
"/ 


strreturn(s, 
len); 


valueptr 
lunct2(arg1, 
arg2) 
valueptr 
arg1, 
arg2; 


" 
lunct2 
takes 
two arguments 
and 
returns 
no value 
"; 


At the top of your C program, you must have the following line: 


#include "ctools.h" 


See the ctooIs.h header file in Appendix A. You may want to 
include other files, such as math.h or stdio.h. depending OI, 
your application. If you use ISFORMIX-ESQLlC, you can include 
sqlca.h and other header files. 
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Before you initialize the required array of ufunc structures, you 
must declare your functions. 


Included in ctools.h is the definition of the value structure and 
of pointers to that structure. 


typedef struct 
value ·valueptr; 
typedef struct 
value ·acevalue; 
typedef struct 
value ·perfvalue; 


The last two pointers are included for compatibility with earlier 
versions of INFORMIX. All of your functions must be of type 
valueptr. If functl( ) and funct2(argl, arg2) are your 
functions, their declarations must come next. 


valueptr 
funct1(); 
valueptr 
funct2(); 


If you place the initialization of the userfuncs array after the 
code that defines your functions, you may skip this step. 


Make the structure declaration and initialization for user- 
funcs[ ] the next section of your program. These structures 
are required so that ACE and PERFORM can call your functions 
at runtime. 


struct 
ufunc userfuncs[] 
I 
"myfunct1". 
funct1. 
"myfunct2". 
funct2. 
0,0 
I. 
" 


The quoted strings, "myfunctl" and "myfunct2", must be 
the names of the functions as they are used in the specification 
file. functl and funct2, which correspond to "myfunctl" 
and "myfunct2", respectively, are pointers to the functions as 
defined within the Cprogram. Note that the C functions as 
defined here need not have the same name that you used in 
your specification file. The purpose of the userfuncs array is 
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I 


II, 


to make the connection between these two names. The two 
zeros at the end of the array are required as terminators. 


The last section of the C program is the code for your func- 
tions. As stated earlier, all of the functions that you call in ACE 
or PERFORM must be declared as returning pointers to a value 
structure. Also, all arguments of your functions must be 
declared of type valueptr. 


The call to strreturn in the definition of functl is an example 
of the use of one of several macros that can be used to return 
values of type valueptr. These and other conversion routines 
are described in a later section. 


Input Parameters 


The ctools.h header file is designed to make the process of 
interfacing C functions to ACE and PERFORM easy. For exam- 
ple, if the parameter passed to the C function is arg, the 
definitions shown below can be used to detect the data type of 
arg and to extract the value of arg, no matter what its data 
type. 


arg->v_charp 
a r g->v_' en 
arg->v_int 
arg->v_' ong 
arg->v_f loat 
arg->v_double 
arg->v_decirnal 
a r g->v_t ype 
arg->v_i nd 


pointer 
to string 
length of string 
integer 
value 
long value 
float 
value 
double value 
dec irna I val ue 
data 
type 
null 
indicator 


The data type of arg can be determined by checking 
arg - >v_type against a series of integer constants defined in 
ctools.h. 
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v_type 
RDSQL Type 
C Type 


( char 
SQLCHAR 
CHAR 
<string 
l fixchar 
SQLSMINT 
SMALLINT 
short 
SQLINT 
INTEGER 
long 
SQLFLOAT 
FLOAT 
double 
SQLSMFLOAT 
SMALLFLOAT 
float 
SQLDECIMAL 
DECIMAL 
dec 
t 
SQLSERIAL 
SERIAL 
long 


SQLDATE 
DATE 
long 
SQLMONEY 
MONEY 
dec- t 


If arg->v_type is SQLCHAR, then the pointer to the string 
is available in arg - >v_ charp, and the number of characters in 
the string (length) is available in arg - >v_len. The string is 
not null-terminated. 


arg->v_ind is negative if the value of arg is NULL and zero, 
otherwise. 


Type Conversions 


ctools.h provides an alternative to testing the type of the 
parameter passed from ACE or PERFORM. Several functions, 
listed below, can force conversion of a parameter passed as a 
pointer to a value structure, to a C data type of your choice: 


Function 


toint 
tolong 
tofloat 
todouble 
todate 
todecimal 


Returned Type 


int 
long 
double 
double 
long 
dec 
t 


These functions take a pointer to a type value structure and 
return a value of the type indicated. todecimal takes a second 
argument that is a pointer to the dec_ t structure. If the type 
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cOl1\'ersion is not successful, the global integer toerrno will be 
set to a negative value, toerrno is zero if the conversion is 
successful. 


Small Machine Features: On small machines. FLOAT and 
SMALLFLOAT variables are converted to DECIMAL in ACE. If you 
pass them as arguments to your C function and want to treat them 
as C doubles or floats, you must convert them using todoubleO or tofioatO. 


Return Values 


\\'hen your function is expected to return a value to ACE or 
PERFOR:\I, you must insert the value in a type value structure 
and return a pointer to that structure. ctools.h contains the 
following macros to perform that procedure for you: 


Macro 


intreturn(i) 
Ingreturn(J) 
floreturn( f) 
dubreturn(d) 
strreturn(s,c) 
decreturn(d) 


Type Returned 


returns integer i 
returns long I 
returns float f 
returns double d 
returns string s of length c (shortl 
returns decimal d (of type dec_tl 


\. 


Use the appropriate macro even when you want to return an 
error condition, Do not use a simple return. 


Since strreturn(s,c) returns a pointer to the string s, be sure 
to define s as a static or external variable. 
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Special PERFORM Library Functions 


Five C functions are designed to control PERFOR!\I screens from 
within C functions: 


pf_nxfield 


determines the type and length of a display 
field on a screen. 


reads a value from a display field. 


puts a value onto a display field. 


moves the cursor to a specified field. 


writes a message at the bottom of the screen. 


These functions are described in detail on the following pages. 
Their return value is zero if successful or a nonzero error code 
if unsuccessful. 


Be sure to note that the argument of pf_getval and 
pf_putval that refers to the value returned or displayed must 
be a pointer to the variable containing the value. A common 
programming error is to use the variable itself. This results in 
a runtime system error and is not detected by the compiler. 
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PF 
GETTYPE 


Overview 


pf_gettype returns the RDSQL data type and the length of the 
display field for a specified field tag. 


Syntax 


pf_gettype(tagname, type, len) 
char *tagname; 
short *type, *len; 


Explanation 


tagname 
is a string containing the field tag that specifies a 
display field. 


type 
is a pointer to a short integer that describes the data 
type of the display field tagname. 


len 
is a pointer to a short integer that is the length of 
the display field tagname on the PERFORM screen. 
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Notes 


1. The following are the possible values of t.\'pe: 


type 


SQLCHAR 
SQLS!\lINT 
SQLINT 
SQLFLOAT 
SQLS!\lFLOAT 
SQLDECIMAL 
SQLSERIAL 
SQLDATE 
SQLMONEY 


RDSQL Type 


CHAR 
S11ALLINT 
INTEGER 
FLOAT 
SMALLFLOAT 
DECI::VIAL 
SERIAL 
DATE 
MOl"EY 


These symbols are defined in ctools.h. 


Return Codes 
o 
The operation was successful; display field was 
found. 


3759 
There is no such field tag in the form. 
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PF 
GETVAL 


Overview 


pf_getval obtains the value found in a display field and its 
length. if it is a character field. 


Syntax 


pf_get\-aI(tagname. ret\"alue. \"aItype. \-alIen) 
char *tagname. *ret\"alue: 
short \"aItype. \"alIen: 


Explanation 


tagname 
is a string containing the field tag that specifies a 
display field. 


retL'alue 
is a pointer to the string. short, long. float. double, 
or decimal structure returned by pf_getval. 


L'Qltype 
is a short integer indicating the type of value to 
which retL'Qlue should point. 


callen 
is a short integer specifying the length of the string 
(plus 1 for the terminating null byte) returned in 
retvalue. when valtype is CCHARTYPE. For any 
other value for valt)pe, vallen is ignored. 
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Notes 


1. The options for valtype are as follows: 


valtype 


CCHARTYPE 
CFIXCHARTYPE 
CSTRINGTYPE 
CINTTYPE 
CSHORTTYPE 
CLONGTYPE 
CFLOATTYPE 
CDOUBLETYPE 
CDECIMALTYPE 


RDSQL Type 


1 
>CHAR 
JINTEGER 
SMALLINT 
INTEGER. DATE. SERIAL 
SMALLFLOAT 
FLOAT 
DECIMAL. MONEY 


2. The type of retvalue is determined by the value given to the 
parameter valtype. valtype need not correspond exactly to 
the data type of the display field, but both should be either 
numeric or character so that PERFORM can do the proper 
type conversion. 


3. If ualtype is numeric and the display field is a character 
field, type conversion is done, if possible. When the conver- 
sion cannot be completed successfully, the numeric pointed 
to by retvalue is zero. If ualtype is character and the 
display field is numeric, a conversion to a string occurs. If 
the string does not fit in the length specified by uallen, 
retualue contains the string, truncated to fit and null- 
terminated. 


Return Codes 
o 
The operation was successful: display field was 
found. 
3700 
The user is not permitted to read the field. 
3759 
There is no such field tag in the form. 
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PF 
PUTVAL 


Overview 


pf_putval puts a value into a PERFORM: screen in a specified 
display field. The user must have permission to update or to 
enter data into the desired destination field. 


Syntax 


pf---put\Oa](p\,alue. \'altype, tagname) 
char *p\'alue: 
short \'altype: 
char *tagname: 


Explanation 


pL'Qlue 
is a pointer to a string, a short, an integer, a long, a 
float, a double, or a decimal structure inserted into 
the display field designated by tagname. 


valtype 
is a short integer indicating the type of value to 
which pualue points. 


tagname 
is a string containing the field tag specifying the 
display field where the information pointed to by 
pvalue is placed. 


6-25 


Notes 


1. The options for valtype are as follows: 


valtype 


CCHARTYPE 
CFIXCHARTYPE 
CSTRINGTYPE 
CINTTYPE 
CSHORTTYPE 
CLONGTYPE 
CFLOATTYPE 
CDOUBLETYPE 
CDECIMALTYPE 


RDSQL Type 


") 
> CHAR 
) 
INTEGER 
SMALLINT 
INTEGER, DATE 
SMALLFLOAT 
FLOAT 
DECIMAL, MONEY 


2. The data type of pvalue is determined by the value given to 
the parameter valtype. 


3. If valtype is one of the character types and the display field 
is a numeric field, type conversion is done, if possible. If 
the conversion cannot be completed successfully, the value 0 
is entered into the display field. 


4. If the type specified is numeric and the display field is 
character, a conversion to a string occurs. If the string does 
not fit in the display field, the display field is truncated. 


5. If a numeric value does not fit in a numeric display field, 
the field is filled with asterisks. 


Return Codes 
o 
The operation was successful; display field was 
found. 
3710 
The user is not permitted to update the field. 
3720 
The user is not permitted to add to the field. 
3756 
The display field is not in the current table. 
3759 
There is no such field tag in the form. 
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PF 
NXFIELD 


Overview 


pf_nxfield controls the cursor placement on a PERFORM 
screen when in an edit mode (either adding a new record or 
updating an old one). 


Syntax 


pf_ nxfield(tagname) 
char *tagname; 


Explanation 


tagname 
is a string containing the field tag for the display 
field on a PERFORM screen to which the cursor is 
sent. 


Notes 


1. If pf_nxfieldis called during a BEFORE EDITADD or a 
BEFORE EDITUPDATE of a table, it controls which 
display field is edited first. 


2. If pf_nxfield is called during an AFTER EDITADD or an 
AFTER EDITUPDATE of a table, it causes the cursor to 
move to the designated display field tagname for further 
editing, rather than to allow the record to be written. 


3. If pf_nxfield is called either BEFORE or AFTER an 
EDITADD or EDITUPDATE of a column, it determines 
the next field to be edited. 


4. If pf_nxfield is called either AFTER ADD or AFTER 
UPDATE, it is inoperative, since the record has already 
been written. 
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5. If tagname is set equal to the value EXITNOW, 
pf_ nxfield causes an immediate exit from the add or 
update operation with the row being added or updated. 
This option performs the same as when you press ESCAPE to 
complete the transaction. 


Return Codes 
o 
The operation was successful; display field was 
found. 
3710 
The' user is not permitted to update the field. 
3720 
The user is not permitted to add to the field. 
3755 
The display field is display-only. 
3756 
The display field is not in the current table. 
3759 
There is no such field tag in the form. 
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PF_MSG 


Overview 


pf_msg displays a message at the bottom of the screen. 


Syntax 


pf_msg(msgstr, reverseflag. bellflag) 
char *msgstr; 
short reverseflag. bellflag; 


Explanation 


msgstr 


reverseflag 


bellflag 


Notes 


is a string containing the message displayed at 
the bottom of the screen. 


is a short integer indicating whether or not the 
message is displayed in reverse video (0 = nor- 
mal video, 1 = reverse video). 


is a short integer indicating whether or not the 
terminal bell is rung whx!1,the message is 
displayed (0 = no bell,~l = bell). 


1. If several calls to pf_msg are invoked at the same time in 
response to satisfying several conditions simultaneously, 
only the last message displayed is visible to the user. 


2. In normal video display, the string can have up to eighty 
characters. In reverse video display, the maximum number 
of characters is less than eighty because the reverse video 
control characters require one or more spaces on some 
terminals. 
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Compiling, Linking, and Running 


After you have written the file containing your C functions, you 
must compile them and link the necessary library functions to 
create a custom version of sacego or sperform. 


After you compile your custom version of sacego or sperform, 
you can run reports or forms with the following command line 


custprog specfile 


where spec-file is the name of the report or form specification 
file you compiled using ACEPREP or FORMBCILD. 


Compiling On UNIX Systems 


Shell scripts are provided to simplify the compiling and linking 
process. You can use these shell scripts as though they were 
the same as the standard C compiler-linker cc. You do not 
have to be concerned with names of special ACE, PERFORM, or 
IXFORMIX-ESQLlC libraries or preprocessors or with the location 
of the include files associated with these programs. 


Syntax 


[eaee I eperf] eprogram·le I ee] I...] -0 custprog other-C-list 


Explanation 


cace 


cperf 


is the shell script that creates a custom version 
of sacego. 


is the shell script that creates a custom version 
of sperform. 
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I 


cprogram 


c 


ec 


o 


custprog 


other-C-list 


Notes 


is the name of the C program that contains 
your functions, as described in the previous 
sections. 


is the extension to use if cprogram has no 
INFORMIX-ESQLlC statements. 


is the extension to use if cprogram has 
INFORMIX-ESQL/C statements (see Chapter 1, 
"Using RDSQL"). 


specifies the output filename. 


is the name of your custom version of sacego 
or sperform. 


is the rest of the arguments that you want to 
pass to the standard cc program. 


1. You can compile several C programs at the same time. 


2. 
In the small machine version of INFORMIX-SQL. PERFORM 
memory requirements are significant, so memory available 
for adding long functions is limited. In particular. 
cprogram cannot use floating-point variables nor contain 
INFORMIX-ESQLlC statements. 


Compiling On DOS Systems 


If your file contains INFORMIX-ESQLlC statements, you must give 
it the extension .EC and use the preprocessor to convert it for 
the C compiler: 


ESQLC CFILE.EC 


where CFILE.EC is the file containing your C functions. If 
successfuL ESQLC produces a file CFILE.C that you can 
compile with your C compiler. If your file does not contain 
IXFOR:mX-ESQLlC statements, you must give it the extension .C. 
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The compilation procedure for Version 3.00 of the Lattice C 
Compiler follows. The compilation must use the middle 
memory model (compiler option -mp) and must seek the 
include files in C:\informix\incl (compiler option 
-iC:\informix\incl). You can use other compiler options as 
appropriate. 


LC -mp -iC:\informix\incl 
CFILE 


produces CFILE.OBJ. 


When you link all the object files you have created to form a 
custom version of PERFORM, you must include the INFORMIX- 
ESQL/C library (LIBSQL.LIB), if you used INFORMIX-ESQLlC state- 
ments, and the PERFORM library (LIBSPERF.LIB). Since ACE 
always uses INFORMIX-ESQLlC (the SELECT statement), L1BSQL 
must always be included along with the ACE library 
(LIBSACE.LIB). Unless you have placed them elsewhere, these 
libraries are located in \informix\lib: 


LINK CP+CFILE1+CFILE2+ ... ,CUSTPROG,NUL, 
\ i n f 0 rmi x\ Ii b\IL I BCPERF I 
L I BCACE:+ 
\ i n for mix \ lib \ L I BSQL+ [ YOUR L I B+ JLCP 


In this example, your object files are CFILEl, CFILE2, ... , and 
the custom version of PERFORM or ACE is named 
CUSTPROG.EXE. If you want a program listing, replace NUL 
with the name of the file to contain the listing. 
YOURLIB is the 
optional name of any other library you require (such as LCMP, 
if you used special math functions). 


If you have a Microsoft C compiler, use the following 
commands to compile and link your programs: 


c I -c -AM c f i Ie. c -I \ i n for mix \ inc I 


I ink 
cf i le,custprog" 
\informix\1 ib\1 ibsperf 
+ \ i n for mix \ lib \ lib s q I 
PERFORM 


I ink cf i le,custprog, ,\informix\1 ib\1 ibsace 
+\informix\1 ib\1 ibsql 
ACE 
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Examples 


The examples in this section are divided between ACE 
applications and PERFORM applications. ACE C functions may 
be used with PERFORM as well. These sample programs are 
delivered with the demonstration database. However, you must 
have I!'FORMIX-SQL to compile and execute these programs. 
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ACE 


Example 1 


Figure 6-1 shows a specification file that calls a user function to 
execute a system command. The program is a_exl.ace in the 
demonstration database. As shown in Figure 6-2, to_unix.c 
contains the user function. 


database 
stores 
end 


define 
function 
to_unix 
end 


select 
* 
from customer 
end 


format 
first 
page 
header 
call 
to_unix("date") 
skip 
1 line 
on 
eve r y 
row 
print 
customer_num, 
3 
spaces, 
fname 
cl ipped, 
1 space, 
Iname 
end 


Figure 6-1. ACE Example 1: Specification File 
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#include "ctools.h" 


va.lueptr 
to_unix(); 


struct 
ufunc 
userfuncs:J 


1 
I 
"to_unix", 
to_unix, 
0,0 
, . 
" 


val ue p t r 
t o_u nix ( s t r i n g) 
valueptr 
string; 


char 
savearea:80J; 


;*copy 
bytes 
from string 
to 
savearea*1 
by cop y ( s t r i ng-> v_ c h a r p, 
s a v ear e a, 
s t r i ng-> v_I en) ; 


I*put 
nul I 
on 
end*; 
s a v ear e a : s t r i n g-> v_I en J=0 ; 


system(savearea) ; 


Figure 6-2. ACE Example 1: to 
unix Function 
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Example 2 


Figure 6-2 shows an ACE program calling a C function that 
computes the square root of a type DECIMAL number. The C 
function uses some of the decimal functions described in 
Chapter 4, "RDSQL Data Types." 
The problem is to compute 
the average and the standard deviation of the total cost of all 
the orders in the stores database. The program is 
a_ex2.ace. As shown in Figure 6-4, decsqrt.c contains the 
user function. 


database 
stores 
end 


define 
funct ion 
decsqroot 
end 


forma t 
on 
every 
row 
print 
order_num. 
t_cost 
on 
I as trow 
skip11ine 
p r i n t 
"The 
a v era get 0 t a lor de r is· 
" 
(total 
of 
t 
cost)/count 
us i n 9 "$#####. ##" 
print 
"Standard deviation 
is 
. 
fl. 
decsqroot«total 
of 
t 
cost·t cost)/count 
- 
«total 
of t 
cost)/count)··2) 
us i n9 "$#####. ##', 
- 
end 


Figure 6-3. ACE Example 2: Specification File 
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I 


r 


#include "ctools.h" 
#include <math.h> 


valueptr 
squareroot(); 


struct 
ufunc 
userfuncs[] 


I 
I 
"decsqroot". 
squareroot. 
O. 
0 
I.,. 


va I uept r 
squareroot (pnum) 
valueptr 
pnum; 


I 
I 
double 
dub; 
dec 
t 
dec; 


;* 
convert 
decimal 
to 
double *; 
dectodbl (&pnum->v_decimal. 
&dub); 


dub = sqr t (dub); 


; * 
con ve r t 
do ubi e 
t 0 
dec i ma I 
*; 
deccvdbl (dub. 
&dec); 


f* 
return 
decimal 
*; 
decreturn(dec); 


Figure 6-4. ACE Example 2: decsqroot Function 
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PERFORM 


Example 1 


It is often useful in database applications to record the 
identification of the entry clerk and the time of data entry with 
the data entered. It is not necessary to require the entry clerk 
to enter these items. The UNIX operating system can identify 
the entry clerk through the login name and can also supply the 
time. Using the techniques described in this chapter, you can 
write a C program to gather these items from the operating 
system and display them on the screen. PERFORM adds them to 
the row when the row is written. 


Figure 6-5 illustrates a form specification file for entering new 
customers into the stores database. The form is in 
p_exl.per. stamp.c contains the function stamptime. 
Assume for the purpose of this example that the customer 
table has two additional columns: entry_clerk and 
entry_time, both of type CHAR(lO). The form automatically 
records the login name of the entry clerk and the time that the 
customer is added to the database. 


The cursor proceeds from the upper· left down through the 
Customer Data by following the order of the fields listed in the 
ATTRIBUTES section. After the Telephone field, the cursor 
moves to the Owner Name field. When the entry clerk presses 


ESCAPE to complete the transaction, the C function stamptime 
is called. 
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database stores 
screen 
i 


Customer Form 


• Entry Clerk 
:[1009 


] [1002 
] 
] 
] 


Slate:[aO] Zipcode:[1007 
] 
] 


Number 
Owner 
Name 
Company 
Address 


Ci t Y 
Telephone 


: [1000 
: [1001 
: [1003 
: [1004 
[ 1.005 


:[1006 
: [1008 


Time Entered 
:[IOtO 
] . 


r 


tables 
customer 


at tributes 
1000 
cus tome r . cus tome r_n um, 
noen try; 
1001 
customer.lname; 
1002 
customer.lname; 
1003 
customer.company; 
1004 
customer.addressl; 
1005 
customer.address2; 
1006 
customer.clty; 
a 0 = 
c us tome r . s tat e, 
del a u It=" CA", 
ups h I It, 
aut 0next ; 
1007 
customer.zipcode, 
autonexl; 
1008 
customer.phone; 
1009 = cuslomer.entryclerk; 
1010 = customer.entry=lime; 


I nst ruct ions 


atter edi tadd edi tupdate 
01 
phone 
nextfield 
= 
1001 


atter 
edi tadd edi tupdate 01 
customer 
call 
stampt ime() 


end 


Figure 6-5. PERFORM Example 1: Specification File 


The function stamptime, called by the form specification file 
when the entry clerk presses ESCAPE to complete the trans- 
action, is listed in Figure 6-6. In addition to the special func- 
tion pf_putval defined earlier in this chapter, stamptime 
uses the system functions time, localtime, and getlogin. 
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The login name of the order taker is obtained from the string 
function getlogin and displayed on the screen under Entry 
Clerk. 


The system time is decomposed into hours and minutes and 
then reconstructed into a string variable put on the screen in 
fOlO, the Time Entered. 


PERFORM then writes the record to the customer table, using 
the data on the screen. 


#inelude <stdio.h> 
# i n e Iud e 
< time. h> 
#inelude "etools.h" 


val u e p t r 
stamp time ( ) ; 


struet 
ufune userfunes[] 


I 
"s tamp time", 
stamp time, 
0,0 
I·I' 


val ue p t r 
stamp time ( ) 


I 
Ion 9 
see 0 n d s, 
time ( ) ; 
e h a r 
use r time [ 10], 
• get log i n ( ) ; 
s t rue t 
t m 
• time r e e, 
• I 0 e a I time () ; 


see 0 n d s 
= 
time ( ( Ion g.) 0); 
timeree = 
loealt ime(&seeonds); 


pfJutval (get login(), 
CCHARTYPE, 
"f009"); 


sprintf(usertime. 
'lO/o02d:%02d", 
time r e e-> t mho u r, 
time r e e-> t m min) ; 


pfJutval (user time. 
CCHARTYPE. 
"fOl0"); 


I 
I 


Figure 6-6. PERFORM Example 1: stamptime Function 
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r 


r 


Example 2 


Ordinarily, you can enter data into only a single row at a time 
on a PERFORM screen. Using the display-only fields allowing 
input, control blocks, and the C function calls described here, 
you can create a display-only screen into which data can be 
entered for several rows at once. After you enter the data and 
press ESCAPE, your C program interrogates the screen and 
writes the actual rows into the tables. 


Figure 6-7 shows an order form. It has room for listing up to 
five items with the quantity and total price. The extension to 
more items is clear both in the entry form and in the C pro- 
gram that follows. Note that all the display fields are either 
display-only fields or are lookup fields based upon the values 
entered into those display-only fields that permit data entry. 


Upon entering the PERFORM program, a function call is made to 
open the stores database. 


To use the form, you must have a list of customer numbers, 
customer_num, for all existing customers. After you enter 
the customer number into display field fOOO, PERFORM displays 
the customer's first and last names and address in the fields 
fOO 1 through f007. The cursor then moves to field fO 10 
(Order Date) where you can begin entering the order descrip- 
tion. Since the default for the Order Date is today, this field 
appears already filled. You can type in an alternative date. 
After you enter data in the fields fO11 and fO12 the cursor 
moves to the list of items and you enter the stock number, 
stock_num, and manufacturer code, manu_code, for the 
first item. PERFORM. displays the description of the stock item 
selected and the unit price. It calls the function st_desc to 
perform a lookup in the stock table and leaves the cursor in 
the field ql, waiting for you to enter a quantity. After you 
enter a quantity, PERFORM computes the total price for that 
item and keeps a running total of all items at the bottom of the 
screen. The cursor then moves to the first column and waits 
for the stock number of the second item. 
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The process continues through the list of items until you type 
ESCAPE and complete the transaction. PERFORM then enters the 
order data into the orders table and each of the items into the 
items table. It also enters the new Order Number on the 
screen. 


When·you leave PERFORM, a call is made to a function to close 
the database. 
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database stores 


screen 


- - _. _ 
- _ .. - -- _. - - _. - --_. -- - - - - ---- - - - - - - 
-- - - _. _. _. - - - .. -- - - - - - - - - - 
. 
ORDER FORM 


Jl'f005 
] 


Stat~:[aoJ 
Zip Code:[f007] 


Customer Number:,fOOO 
Company Name::1003 
Address:: 1004 
Cit y: : f 006 


Contac! 
Name::fOOl 
] [f002 


Order 
No: r 1009 
J 
Order Date:: fOl0 
Shipping 
Instructions:[f012 
Purchase Order No: [fOll 
] 
- - - - _ .. _. - _. - - _ .. - - - - - -... - _. - - - _ .. - - - - - -.... - - - - _. _ .. _ ... - _.... - - - _. ---- - - _ .. - 


r 


Stock 
sn, 
,sn2 
:8n3 
"sn4 


sn5 


END 


No. 
Code 
Descript ion 


[me 1 J 
[de1 
:mc2; 
: de2 


rmc31 
[de3 
~mc4j 'de4 
. 
,mc5; 
.de5 
Running Total 
including Tax 


Quan tit 
q' 
q2 
q3 
q4 
q5 
and Sh i P 


Price 
Total 
p r 1 
[t P 1 
P r 2 
[t p2 
Pr3 
[ t p3 
P r4 
[ t p4 
P r5 
J [t p5 
ng Charges:[rt 


tables 
customer 
orders 
items 
stock 


today; 
type date, 
de1ault 
type char; 
type char; 


f009 
fOl0 
fOl' 
1012 


attributes 
fOOO 
= displayonly allowing 
input 
type 
integer, 
lookup 
fOOl 
customer.fname, 
f002 
customer.lname, 
f003 
customer.company, 
f004 
customer.addressl, 
f005 
customer.address2, 
f006 
customer.city, 
aO = customer.state. 
f007 
= customer.zipcode 
joining ·customer.customer_num; 
displayonly 
type 
integer; 
displayonly allowing 
input 
dis P Ia yon I y a II ow i ngin put 
displayonly allowing 
input 


snl 
d splayonly 
a I Iowi ng 
input 
type 
sma I lint; 
mcl 
d splayonly al 
owi ng 
input 
type char, 
upshift; 
ql 
d splayonly al 
owi ng 
input 
type 
sma I lin t ; 
sn2 
d splayonly al 
owi ng 
input 
type 
sma I lin t ; 
mc2 
d splayon 
y al 
owi ng 
nput 
type char, 
upshift; 
q2 
d splayon 
y al 
owi ng 
nput 
type sma 1lin t; 
sn3 
d splayon 
y al 
owi ng 
nput 
type sma II in t; 
mc3 
d splayon 
y al 
owi ng 
nput 
type char, 
upsh if t ; 
q3 
d splayon 
y al 
owi ng 
nput 
type sma I lin t; 
sn4 
d splayon 
y al 
owing 
nput 
type 
sma II in t; 
mc4 
d splayon 
y al 
owing 
nput 
type char, 
upsh if t ; 
q4 
d splayon 
y al 
owi ng 
nput 
type sma I lint; 
sn5 
d splayon 
y al 
owi ng 
nput 
type smallint; 
mc5 
dlsplayon 
y al 
owi ng 
nput 
type char, 
upsh if t ; 


q5 
displayon 
y al 
owi ng 
nput 
type 
sma I lin t ; 


del 
displayonly 
type char; 
p r 1 
displayonly 
type money, 
r i gh t ; 
t p' 
dispt'ayonly 
type money, 
r i gh t ; 
de2 
displayonly 
type char; 
pr2 
displayonly 
type money, 
r i gh t ; 


6-43 


tp2 
displayonly 
type money. 
r i gh t ; 
de3 
displayonly 
type 
char; 
pr3 
displayonly 
type money. 
r i gh t ; 
tp3 
displayonly 
type money. 
r i gh t ; 
de4 
displayonly 
type char; 
pr4 
displayonly 
type money. 
r i gh t ; 
tp4 
displayonly 
type money. 
r i gh t ; 
deS 
displayonly 
type 
char; 
prS 
displayonly 
type money. 
r i gh t ; 
tpS 
displayonly 
type money. 
r i gh t ; 
rt 
displayonly 
type money. 
reverse, 
r i gh t ; 


instructions 
alter 
editadd 
01 
mcl 
il 
st_desc(l) 
then 
next!ield=ql 
else 
begin 
conments 
"Not 
a valid 
stock 
item" 
let 
snl 
= 
null 
let 
mc I 
= 
nul I 
nextfield = 
snl 
end 
a 1 t ere d ita ddol 
mc 2 
il 
st_desc(2) 
then 
nextlield = 
q2 
else 
begin 
conments 
"Not 
a valid 
stock 
item" 
letsn2=null 
let 
mc2 = 
nul I 
nextlield = 
sn2 
end 
al ter 
ed i tadd 
01 
mc3 
if 
st_desc(3) 
then 
nextfield=q3 
else 
begin 
conments 
"Not 
a valid 
stock 
item" 
let 
sn3 = 
null 
let 
mc3 = 
nul I 
next! ield = 
sn3 
end 
after 
editadd 
01 
mc4 
il 
st_desc(4) 
then 
nextfield = 
q4 
else 
begin 
conments 
"Not 
a 
val id 
stock 
item" 
let 
sn4=null 
let 
mc4 = 
nul I 
next! ield = 
sn4 
end 
a I t ere d i Is ddol 
mc S 
il 
st__desc(S) 
then 
next!ield = 
qS 
else 
begin 
conments 
"Not 
a valid 
stock 
item" 
let 
snS=null 
let 
mcS = 
null' 
next!ield 
sn'S 
end 
alter 
editadd 
01 
ql 
let 
tpl 
= 
ql 
• prl 
let 
rt 
= 
tpl 
• I. I 
after 
edi tadd 
01 
q2 
let 
tp2 
= 
q2 
• 
pr2 
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l 


\..... 


leI 
rl 
= 
(lp1 + Ip2) 
• 
1.1 
after 
ediladd 
of 
q3 
let 
Ip3 = 
q3 
• 
pr3 
leI 
rl 
= 
(lp1 + Ip2 + Ip3) 
• 
1.1 
afler 
ediladd 
of 
q4 
leI 
Ip4 = 
q4 
• 
pr4 
leI 
rl = (lp1 + Ip2 + tp3 + tp4) 
• 
1.1 
afler 
ediladd 
of 
q5 


leI 
Ip5 = 
q5 
• 
pr5 
leI 
rl 
= 
(lp1 + tp2 + Ip3 + tp4 + Ip5) 
• 
1.1 
before ediladd 
of 
displaylable 
elde1=null 
el 
de2 = 
null 
et 
de3 = null 
e I 
de4 
= 
nul I 
e I 
de5 
= 
nul I 
el 
pr1 = null 
el 
pr2 = 
nu II 
el 
pr3 
= 
null 
et 
pr4 
= 
nul I 
el 
pr5 = 
nu II 
et 
Ip1 
= null 
e I 
I p2 = 
nul I 
e I 
I p3 
= 
nul I 
e I 
I p4 = 
nul I 
leI 
Ip5 = 
null 
let 
r I 
= 
nu I I 
afler 
editadd of 
displaylable 
leI 
f009 
= 
add__order() 
end 


Figure 6-7. PERFORM Example 2: Specification File 


PERFORM calls st_desc when you leave the Code field for each 
item, and add_order when you type ESCAPE. These functions 
are listed in Figure 6-8. In addition to the C functions defined 
in this chapter, the program uses some functions from Chapter 
5, "Library Functions," as well as INFORMIX-ESQL/C. 


st_desc gets the values that you entered for stock_num and 
manu 
code and checks whether or not either is NULL. If 
not, it selects the description and unit-.-J)rice for the stock 
item defined by stock_num and manu_code, displays them 
on the screen, and returns the value 1 (true). If either of 
stock_num or manu--,-code is NULL or if thereis no item in 
the stock table corresponding to them, st_desc returns 0 
(false). 


6-45 


add_order begins by checking whether or not any items have 
been entered. If not, it writes a message saying that no order 
has been written and returns. If at least one item has been 
entered, add_order collects the information about the order 
and starts a transaction. After inserting a new row in the 
orders table, add_order enters a loop to insert each item of 
the order into the items table. It determines whether or not to 
insert a row into the items table by testing to see if the total 
price for that row is not NULL. Only if all of the changes to 
the database corresponding to the order are made successfully, 
is the work committed and the order actually entered. 
add_order returns the value of the order_Dum for PERFORM 
to display on the screen. The form is in p_ex2.per. 
mult 
item.ec contains the C functions. 
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#include <ctools.h> 
$include 
sqlca; 


extern 
valueptr 
st_desc(); 
extern 
valueptr 
add_order(); 


struct 
utunc 
userfuncs~: 


"st_desc", 
st_desc, 
"add_order", 
add_order, 
0.0 


char ·snL J = 
: 


"sn1". 
nsn2 tt , 
nsn3 tt , 
"8n4n , 
"sn5 tt 


" 
c h a r 
• me ~ 
~ 
= 
: 
ttmc1", 
ttmc2 tt , 
ttmc3u , 
ttmc4", 
"meS" 


char 
·de~~ =: 
"de1", 
nde2", 
"de3" . 
ttde4 tt , 
"de5" 
,. 
" 
char *q:: - , 
- 
, 
"q1", 
"q2 n • 
nq3u , 
"q4 n , 
"q5 n 


char·pr~~=l 


"pr 1". 
"pr2u , 


ttp r3" 
I 
"pr4". 
"pr5" 


" 
char·tp~~,=l 


tttp1". 
"t p2tt , 
ntp3 tt • 
"tp4 tt , 
"tp5" 
,.,. 


valueptr 
st_desc(item) 
valueptr 
item; 


$ 
in t 
s; 
$ 
charm:<; 


$ 
char < 16: 
$ 
dec_t 
up; 
in t 
i; 


i 
= 
it em-> v 
in t 
- 
1, 


pf_getval(sn:ij, 
as, 
CINTTYPE, 
0); 


pf_getval(mc~iJ, m, 
CCHARTYPE. 
4); 
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if 
(risnull(CINTTYPE, 
as) II 
risnull(CCHARTYPE, 
m» 
inlrelurn(O); 
iO 
reI urn 
lalse il 
eilher 
lield nullo/ 


$ 
selecl 
de'scriplion, 
unil---.price 
inlo $d, 
$up 
from slock 
where 
slock_num = 
$s 
and manu_code = 
$m; 
i I 
(sqlca.sqlcode == 0) 
, 
I 
pl---.pulval (d, 
CCHARTYPE. 
de~ i 1)' 


P I---'p u I val (& up, 
CDEC IMAL TYPE. " p; [ i ] ) ; 
inlrelurn(1); 


else 
inlrelurn(O); 


valueplr 
add_order() 


$ 
iong cuslno; 
$ 
long o_dale; 
$ 
char ponum[11;; 


$ 
char 
instr[41J; 
$ 
long onum; 
$ 
inl 
sIno; 
$ 
char manc[4J; 
$ 
inl 
quan; 
$ 
dec_1 
lotal; 
$ 
inlit no; 
in t 
i; 
char errsl r[80J; 


/° lin d 
0 u I 
wh e I her 
any 
i I ems 
we rei i s led 
i nor de r °/ 
pl_gelval("lp1", 
&Iotal, 
CDECIMALTYPE, 
0); 
il 
(risnull(CDECIMALTYPE, 
&Iolal» 
,, 
pl_msg("No 
ilems 
entered. 
no order 
recorded", 0,1); 
pl_nxl ield("sn1"); 
Ingrelurn(O); 


/0 
co I I ec I 
da I a 
lor 
I he 
0 r de r s 
row °/ 
pl_gelval("IOOO", 
&cuslno, 
CLONGTYPE, 
0); 
pl_gelval("1010". 
&o_dale, 
CLONGTYPE, 
0); 
p I_gel va 1("1011", 
pon urn. 
CCHARTYPE, 11) ; 
pl_getva 1("1012", 
i nsl r, 
CCHARTYPE ,41); 


/0 
begin 
Iransaclion 
0/ 
$ 
begin work; 
/0 
inserl 
order 
dala 
inlo orders 
lable 
0/ 
$ 
inserl 
inlo orders 
(order_num, 
cuslomer_num. 
order_dale. 
po_num. 
sh i p_i nsl rucl) 
values(O, 
$cuslno. 
$o_dale. 
$ponum, 
$inslr); 
il 
(sqlca.sqlcode 
1= 0) 
I 
spr i nl I (er rsl r, 
"error 
number 
%d 
in 
i nserl", 
sql ca. sq I code); 
p I_msg (e r r sIr, O. 1) ; 
$ 
rollback work; 
Ingrelurn(O); 
,, 
onum = 
sqlca.sqlerrd[1]; 
/0 
gel 
serial 
value 
assigned 
0/ 


/0 
co I I ec I 
da I a lor 
i I ems 
I ab leo / 
lor 
(i=0;i<5;i++) 
, 
I 
pl_gelval(sn i]. 
&slno, 
CINTTYPE, 
0); 
pl_gelval(mc I]. 
manc. 
CCHARTYPE, 
4); 
pl_gelva I (q[ 
j. 
&quan, 
CINTTYPE, 
0); 
pl_gelval{lp i]; 
&Iolal. 
CDECIMALTYPE, 
0); 
i I 
{! 
r i s nul 
(CDEC 1MALTYPE. 
& 10 I a I ) ) 
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$ 


$ 


Ino = 
+ 1; 
nsert 
nto 
items 
values 
($ 
Ino, 
$onum, 
$slno, 
$manc, 
$quan, 
$Iolal); 
if 
(sqlca.sqlcode 
!= 0) 
. 
I 
sprintf(errslr, 
"error 
number 
"loci 
in 
update", 
sqlca.sqlcode); 
pf_msg(errslr, 
0,1); 
rollback work; 
Ingrelurn(O) ; 


$ 
commi 1 work; 
Ingrelurn(onum); 


Figure 6-8. PERFORM Example 2: st_desc and add_order Functions 
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Appendix A 


Header Files 


This appendix contains the following header files: 


sqlca.h 
sqlda.h 
sqIstmtype.h 
sqltypes.h 
decimal.h 
ctooIs.h 


is for error codes. 
is for dynamically defined statements. 
is for RDSQL statement types. 
is for RDSQL and C data types. 
is for DECIMAL data types. 
is for ACE and PERFORM applications. 


sqlca.h 


s t r uc t 
s q Ic a_s 


I 
I 
long sqlcode 
char sqlerrm 72J; 
/* error message parameters 
*/ 
char sqlerrp 8]; 
long sqlerrd 6J; 
/* 
0 
re erved 
*/ 
/* 
1 
serial 
value after 
insert 
or 
ISAM error 
code 
*/ 
/* 
2 
number 
of 
rows processed 
*/ 
/ * 3 
est i ma ted cos t 
* / 
/* 
4 
offset 
into of 
an error 
*/ 
/ * 5 
row ida f t e r 
in se r t 
* / 
struct 
sqlcaw_s 


char 
sqlwarn4; 
/* 


char 
sqlwarn5; 
char 
sqlwarn6; 
char 
sqlwarn7; 
: sq Iwarn; 
,. 


" 


W 
W 
W 
W 


/ * 
/ * 
/ * 
/ * 


a~y of sqlwarn[1-7J = W */ 
any truncation occurred 
*/ 
a nul I value returned 
*/ 
no. 
in select 
list 
!= no. 
n into list 
*/ 
W 
f 
no where clause on prepared 
pdate, 
delete 
*/ 
/* 
reserved 
*/ 
/* 
reserved 
*/ 
/* 
reserved 
*/ 


sqlwarnO; 
sqlwarnl ; 
sqlwarn2; 
sqlwarn3; 


I, 
char 
char 
char 
char 


extern struct 
sqlca_s sqlca; 


#def ine SQLNOTFOUND 
100 
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sqlda.h 


#ilndel _SQLDA 
Ide line _SQLDA 


struct 
sqlvar_struct 


short 
sqltype; 
short 
sqllen; 
char 
·sqldata; 
short 
°sqlind; 
char 
°sqlname; 
c h a r 
° s q I lor ma t 
/. 
" 
struct 
sqlda 


1° 
variable 
type 
°1 
1° 
length 
in 
bytes 
° 1 
1° 
pointer 
to 
data 
"I 
1° 
pointer 
to 
indicator 
°1 
1° 
variable 
name ° 1 
1° 
reserved 
lor 
luture 
use ° 1 


short 
sqld; 
struct 
sqlvar_struct 
°sqlvar; 
/. 
I, 


lend i I _SQLDA 
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( 


sqIstmtype.h 


Ide fine 
SCLDATABASE 
1 
Ide fine 
SCLSELECT 
2 
I * 
(not 
used) 
* I 
#def i ne 
SO SELINTO 
3 
#def i ne 
SO_UPDATE 
4 
#def i ne 
SCLDELETE 
5 
#define 
SCLINSERT 
6 
#def i ne 
SCLUPDCURR 
7 
#define 
SCLDELCURR 
8 
#de fine 
SCLLDINSERT 
9 
I * 
(not 
used) 
* I 
#de f . ne 
SCLLOCK 
10 
#def 
ne 
SO 
UNLOCK 
11 
#def 
ne 
SCLCREADB 
12 
#def 
ne 
SCLDROPDB 
13 
#def 
ne 
SCLCRETAB 
14 
#def 
ne 
SO DRPTAB 
15 
#def 
ne 
SCLCRE IDX 
16 
#def 
ne 
SO DRPIDX 
17 
#def 
ne 
SCLGRANT 
18 
#de fine 
SCLREVOKE 
19 
#def i ne 
SCLRENTAB 
20 
#define 
SO RENCOL 
21 
#de fin e 
SCLCREAUD 
22 
#def 
ne 
SCLSTRAUD 
23 
1* 
(n 0 t 
used) ·,/ 
#def 
ne 
SO STPAUD 
24 
I * 
(not 
used) 
* I 
#def 
ne 
SCLDRPAUD 
25 
#def 
ne 
SCLRECTAB 
26 
#def 
ne 
SCLCHKTAB 
27 
I * 
(not 
used) 
• I 
#def 
ne 
SO REPTAB 
28 
I * 
(not 
used) 
• I 
#def 
ne 
SO ALTER 
29 
#def 
ne 
SCLSTATS 
30 
#def 
ne 
SCLCLSDB 
31 
#def 
ne 
SO_DELALL 
32 
#def 
ne 
SCLUPDALL 
33 
#def 
ne 
SO_BEG\MJRK 
34 
#deflne 
SCLCOMv1I T 
35 
#define 
SCLROLLBACK 
36 
#def i ne 
SCLSAVEPOINT 
37 
I * 
(not 
used) ·/ 
#def i ne 
SO__STARTDB 
38 
#define 
SCLRFORWARD 
39 
#de fin e 
SO_CREVI8N 
40 
#def i ne 
SCLDROPVI8N 
41 
Ide fine 
SCLDEBUG 
42 
I * 
(not 
used) 
• I 
#def i ne 
SCLCREASYN 
43 
#define 
SCLDROPSYN 
44 
#define 
SCLCTEMP 
45 
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sqltypes.h 


#ifndef 
CCHARTYPE 


1* C language types 
*1 


#define CCHARTYPE 
100 
#define CSHORTTYPE 
101 
#def 
ne CINTTYPE 
102 
#def 
ne CLONGTYPE 
103 
#def 
ne CFLOATTYPE 
104 
#def 
ne CDOUBLETYPE 
105 
#def 
ne CDECIMALTYPE 
107 
#def 
ne CFIXCHARTYPE 
108 
#def 
ne CSTRINGTYPE 
109 
#deflne CDATETYPE 
110 
#def ine CMONEYTYPE 
111 


#define USERCOLL(x) 
( ( x ) ) 


1* 
* Define all 
possible database types 


* 
inc Iud e C- ISAM t Ypes her e a s we I I as 
i n 
i sam. h 


* 1 


#de fin e SOL CHAR 
#def ine SOLSMINT 
#def i ne SOL INT 
#define SOLFLOAT 
#define SOLSMFLOAT 
#def ine SOLDECIMAL 
#define SOLSERIAL 
#def ine SOLDATE 
#def ine SOLMONEY 
#define SOLNULL 
#def i ne SOL TYPE 
#define SOLNONULL 


o 
1 
2 
3 
4 
5 
6 
7 
8 
9 
OxF/* 
type mask*1 
04001* disallow nulls*1 


1 * t his 
i s 
not are a I t YPe but 
a 
f Ia g t 0 show t hat 
the 


* val ue 
i s 
from a h 0 s t 
va ria b Ie 


* 1 
#def ine SOL HOST 
01000 
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#def i ne SIZCHAR 
#def i ne SIZSMINT 
#def ine SIZINT 
#def ine SIZFLOAT 
#def ine SIZSMFLOAT 
#def ine SIZDECIMAL 
#def ine SIZSERIAL 
#def ine SIZDATE 
#def jne SIZMONEY 


#def ine 
ISDECTYPE(t) 


#def ine DEFDECIMAL 
#def ine DEFMONEY 
#def ine DATENULL 


#def ine SYSPUBLIC 


#endi f CCHARTYPE 


#def ine SIZCHAR 
#def ine SIZSMINT 
#define SIZINT 
#def jne SIZFLOAT 
#def jne SIZSMFLOAT 
#def jne SIZDECIMAL 
#def ine SIZSERIAL 
#def ine SIZDATE 
#def ine SIZMONEY 


#de fine 
ISDECTYPE (t ) 


/* default 
decimal (16) 
#def ine DEFDECIMAL 
/* default 
decimal (16) 
#def ine DEFMONEY 
#def ine DATENULL 


#def ine SYSPUBLIC 


#endif 
CCHARTYPE 


1 
2 
4 
(sizeof(double» 
(sizeof(float» 
17 / 0 
dec ima I (32) 
* / 
4 
4 
17 / * dec ima I (32) 
* / 


«(t)&SOLTYPE)==SOLDECIMAL 
\ 
I I 
«t)&SOLTYPE)==SOLMONEY) 


9 / * de f a u ltd e c ima I ( 16 ) 
s i ze * / 
9 / * de f a ultd e c i ma I ( 16) 
s i ze * / 
Ox80000000L 


"pub Ii c" 


1 
2 
4 
(sjzeof(double» 
(s i zeof( f Ioat» 
17 / * dec i ma I (32) 
0 
/ 
4 
4 
17 / * dec ima I (32) 
* / 


«(t)&SOLTYPE)==SOLDECIMAL\ 
I I 
«t)&SOLTYPE)==SOLMONEY) 


size 
0/ 
9 
size 
0/ 
9 
Ox80000000L 


"pub Ii c" 
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; * 
* Unpacked Format 
(format 
for 
program usage) 


* 
* 
* 
* 
* 
* ; 


Signed exponent "dec_exp" ranging 
from -64 
to +63 
Separate sign 
of mant issa "decJos" 


Base 
100 digits 
(range 0 - 
99) with decimal 
point 
imme d iate I y tot he 
Ieft off irs t dig it. 


#ifndef 
DECSIZE 
#def ine DECSIZE 
16 
#def ine 
DECUNKNOWN -2 


s t r uc t 
dec i ma I 


;* 
exponent 
base 
100 *; 


sho r t 
dec_exp; 


;* sign: 
1=pos, 
O=neg, -1=null 
*; 


sho r t decJos; 
;* 
number 
of significant digits 
*; 


shor t 
dec 
ndgt s; 


;* actual digits base 
100 
*/ 


char 
dec_dgts[DECSIZE]; 
I·I' 
typedef struct 
decimal 
dec_t; 


; * 
* 
* 
* 
* ; 


A dec ima I 
nul lis 
rep res e n ted 
i n t ern a I Iy by set tin g decJ°s 
equal 
to DECPOSNULL 


A-8 decimal.h 


I -Ir/ 


#de fine 
DECPOSNULL (-1 ) 


/. 
• 
DECLEN calculates minumum number 
of 
bytes 
• 
nee e s s a r y 
t 0 
hoi dad e c ima I (m, n ) 
• where m,= total 
# significant digits 
and 
• 
n = s i g n i fie ant 
dig its tor i gh t 
0 f dec ima I 
·/ 


#def ine DECLEN(m,n) 
#def ine DECLENGTH(len) 
( ( (m)+ ( ( n ) & 1 )+3) /2) 
DECLEN(PRECTOT(len),PRECDEC(len» 


/. 
• 
DECPREC calculates 
a default 
precision given 
• 
number 
of 
bytes used 
to store number 
·/ 


#def ine DECPREC(size) 
«(size-l)«9)+2) 


/. macros 
to 
look at 
and make encoded decimal 
• precision 
• 
••••••·/ 


PRECTOT(x) 
return 
total 
precision 
(digits total) 
PRECDEC(x) 
return decimal 
precision 
(digits 
to right) 
PRECMAKE(x,y) 
make precision 
from total 
and 
decimal 


#define PRECTOT(x)«(x»>8) 
& Oxff) 
#define PRECDEC(x)«x) 
& Oxff) 
#def ine PRECMAKE(x,y) 
«(x)«8) 
+ 
(y» 


/. 
• Packed Format 
• 
( for ma tin 
r e cor ds. i n 
f i Ie s ) 
•••• 
•••••••·/ 


Fi rst 
byte 
top 
1 bit = sign 
O=neg, 
l=pos 
Iow 7 bit s = Ex po nen tin 
ex ce s s 64 
for ma t 
Rest 
of 
bytes = base 
100 digits 
in 
100 
complement 
format 
Notes - 
This 
format 
sorts numerically with 
just 
a simple byte 
by byte unsigned 
comparison. 
Zero 
is represented as 
80,00,00, ... 
(hex). 
Negat ive numbers have 
the exponent 
complemented and 
the base 
100 
digits 
in 
1-00's complement 


#endif 
DECSIZE 
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/. 
• 
This 
i s the 
1 i Ie wh i c h mu s t 
be 
inc Iud edin any C sub r 0 uti ne sou r C e 
• 
1 i Ie which 
is 
to be 
I inked 
to 
I ibsace.a and 
I ibsperl .a. 
·/ 


#deline OECSIZE 
16 
#deline OECUNKNOWN 
-2 


struct 
decimal 


sho r t 
sho r t 
short 
char 


dec_exp; 
decJos; 
dec_ndgts; 
dec_dgts:OECSIZE:; 


/" 
exponent 
base 
100 
/ 
/" 
sign of 
number 
l=pos, 
O=neg 
'/ 
/" 
number 
01 significant digits 
" 
," actual digIts base 
100 
'/ 


typedel struct 
decimal 
dec_t; 


/' 
C language types 
"/ 


Ide! ine CCHARTYPE 
100 
#deline CSHORTTYPE 
101 
#deline CINTTYPE 
102 
#del ine CLONGTYPE 
103 
#deline CFLOATTYPE 
104 
#deline COOUBLETYPE 
105 
#deline CBYTETYPE 
106 
#def ine CDECIMALTYPE 
107 
#define CFIXCHARTYPE 
108 
#define CSTRINGTYPE 
109 
#deline CDATETYPE 
110 
Ide fine CM)NEYTYPE 
111 


#define USERCOLL(x) 


I " 


« x» 


• Define al I possible database 
types 
• 
inc Iud e C-I SAM t ypes her e a s we I I as 
i n i sam. h 
·/ 


Ide 1 i ne SQLCHAR 
#define SQLSMINT 
#deline SQLINT 
Ide 1 i ne SQLFLOAT 
#deline SQLSMFlOAT 
#del ine SQlDECIMAl 
#deline SQlSERIAl 
#deline SQlDATE 
#deline SQlMONE 
#deline SQlNUll 
#de 1 i ne SQLTYPE 
#deline SQlNONUll 
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o 
1 
2 
3 
4 
5 
6 
7 
8 
g 
OxF 
0400 
/' 
type mask 
disallow nulls 
., 
" 


this 
is 
not 
a 
real 
type 
but 
a 
lIag 
to 
show that 
the 
" 
value 
is 
Irom 
a host 
variable 


" 
I 


#del i ne 
SOLHOST 


#deline 
DATENULL 


struct 
value 


01000 


OxBOOOOOOOL 


short 
v_type; 
shorl 
v_ind; 
shor t 
vJrec; 


union 


i" 
type 
01 
value, 
determines 
i" 
null 
indicator 
/" 
decimal 
precision 
/" 
wh i c hoi 
f 0 I low i n9 
is 
val i d 


" /" / 
" /" / 


struct 
/" 
char 
value 
(not 
null 
terminated) 
"/ 


char 
"vcp; 
short 
vidx; 
short 
vlen; 


1 vcha r ; 
in t 
vi n t ; 
long 
vlng; 
I loa t 
v I 10; 
double 
vdub; 
dec_t 
vdec; 
: v_va I; 


I" 
pt r 
to 
char 
st ring 
value 
I" 
unused 


/ " 
len 
01 
char 
s t ring 
value 


/. integer 
value 
I" 
long 
value 
(also dates) 
/. I loa t 
value 
I' 
double value 
/. decimal 
value 
(also money) 


" I" / 
" I 


" I./ 
" /" /" / 
,. 
" 
#deline 
v_charp 
#deli ne 
v_I ndex 
#deline 
v_len 
#del i ne 
v_I nt 
#del i ne 
v_long 
#de line 
v_I loa t 
#deline 
v_double 
#deline 
v_decimal 


v_va I. vchar. vcp 
v_val.vchar.vidx 
v_val.vchar.vlen 
v_val.vint 
v_va I. v I ng 
v_val.vllo 
v_val.vdub 
v_val.vdec 


typedel 
struct 
value" 
valueptr; 
typedel 
struct 
value" 
acevalue; 
typedef 
struct 
value" 
perlvalue; 


extern struct 
value 
retstack; 


\ .. 


#de lin e 
i n t ret urn ( i ) 


#deline 
Ingreturn(i) 


Ide Ii nell 0 ret urn (d) 


#deline dubreturn(d) 


#deline strreturn(s,c) 


:retstack.v 
type=SOLSMINT;\ 


retstack.v'=;nt=(i);\ 
return(&retstack) ;J 


Iretstack.v_type=SOLINT;\ 
retstack.v_Iong=(i);\ 
return(&retstack) ;1 


Iretstack.v 
type=SOLSMFLOAT;\ 


retstack.v.=!loat=(d);\ 
return(&retstack) ;: 


Iretstack.v 
type=SOLFLOAT;\ 
retstack.v~ouble=(d);\ 
return(&retstack) ;1 


Iretstack.v 
type=SQLCHAR;\ 
retstack. v3harp=(s); \ 
retstack. v_len=(c); \ 
return(&retstack) ;: 
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#def ine decreturn(d) 
:retstack.v_type=SQLDECIMAL;' 
dec cop y ( &d. 
& ret S t a c k . v_de c i ma I ) ; \ 
return(&retstack) ;: 


#define 
intcon 
toint 
#define 
longcon 
tolong 
#define 
dubcon 
todouble 


struct 
ufunc 


char 
'uf_id; 
struct 
value 
'('uf_func)(); 


I' 
• 
The structure declaration 
for 
"userfuncs" 
• 
must 
be 
put 
in 
the 
user's data 
area. 
• 
A hypothetical 
case 
using 
the 
user 
C functions 
• 
called nuserfuncl" and "userfunc2"is 
shown 
below. 


valueptr 
userfunc1(); 
valueptr 
userfunc2(); 
These 
routines must 
be 
externed before 
the 
userfuncs structure 
is 
initialized 


struct 
u'1unc 
userfuncs~-: 


ttuserfunc1 t'. 
userfuncl, 


tt use r fun c 2n. 
-u s e r fun c2 . 
_____---'Pointer 
to 
the 
user 
function. 
The 
name of 
the 
user 
funct ion 
------------------------as defined 
in 
the 
DEFINE 
statement 
of 
ACE. 
0,0 <:------------Note 
that 
this array must 
be 
terminated 
by 
two 
zeros. 
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• 
These structures are 
required 
so 
that 
ACE 
• 
can call 
the 
user 
subroutines 
• 
a t 
run 
time. 


• I 
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System Catalogs 


Information about the database is maintained in the system 
catalogs. The system catalogs are as follows: 


systables 
syscolumns 
sysindexes 
systabauth 
,syscolauth 
sysdepend 
syssynonyms 
sysusers 
sysviews 


describes database tables. 
describes columns in tables. 
describes indexes on columns. 
identifies table-level privileges. 
identifies column-level privileges. 
describes how views depend on tables. 
lists synonyms for tables. 
identifies database-level privileges. 
defines views. 


The following list gives a brief description of the system 
catalogs. 


The SYSTABLES Catalog 


Column 
Name 


tabname 
owner 
dirpath 
tabid 
rowsize 
ncols 
nindexes 
nrows 
created 
version 
tabtype 
audpath 


Index 
Name 


tabname 
tabid 


Type 


char(l8) 
char(8) 
char(64) 
serial 
smallint 
smallint 
smallint 
integer 
date 
integer 
char(l) 
char(64) 


Type 


unique 
unique 


Explanation 


name of table 
owner of table 
directory path for the table file 
internal table identifier 
rov.' size 
number of columns 
number of indexes 
number of rows 
date created 
table version number 
table type (T = table, V = view) 
audit filename (full pathname) 


Columns 


tabname, owner 
tabid 
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The SYSCOLUMNS Catalog 


Column 
Name 


colname 
tabid 
colno 
coltype 
collength 


Index 
Name 


column 


Type 


char(l8) 
integer 
smallint 
smallint 
smallint 


Type 


unique 


Explanation 


column name 
table identifier 
column number 
column type 
column length (physical) 


Columns 


tabid, colno 


The SYSINDEXES Catalog 


Column 
Name 


idxname 
owner 
tabid 
idxtype 
clustered 
partI 
part2 
part3 
part4 
part5 
part6 
part7 
part8 


Index 
Name 


idxtab 
idxname 
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Type 


char(l8) 
char(8) 
integer 
char(l) 
char(l) 
smallint 
smallint 
smallint 
smallint 
smallint 
smallint 
smallint 
smallint 


Type 


dupls 
unique 


Explanation 


index name 
owner of index 
table identifier 
index type (U = unique, D = dups) 
clustering 
column number 
column number 
column number 
column number 
column number 
column number 
column number 
column number 


Columns 


tabid 
idxname, tabid 


The SYSTABAUTH Catalog 


Column 
Name 


grantor 
grantee 
tabid 
tabauth 


Index 
Name 


tabgtor 
tabgtee 


Type 


char(8) 
char(8) 
integer 
char(7) 


Type 


unique 
dupls 


Explanation 


grantor of permission 
grantee (receiver) of permission 
table identifier 
authorization type 


Columns 


tabid, grantor, grantee 
tabid, grantee 


The SYSCOLAUTH Catalog 


Column 
Name 


grantor 
grantee 
tabid 
colno 
colauth 


Index 
Name 


colgtor 
colgtee 


Type 


char(8) 
char(8) 
integer 
smallint 
char(2) 


Type 


unique 
dupls 


Explanation 


grantor of permission 
grantee (receiver) of permission 
table identifier 
column number 
authorization type 


Columns 


tabid, grantor, grantee, colno 
tabid, grantee 
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The SYSDEPEND Catalog 


( 


Column 
Name 


btabid 
btype 
dtabid 
dtype 


Index 
Name 


btabid 
dtabid 


Type 


integer 
char(l) 
integer 
char(l) 


Type 


dups 
dups 


Explanation 


tabid of base table or view 
base object type (table or view) 
tabid of dependent table 
dependent object type (only view now) 


Columns 


btabid 
dtabid 


The SYSSYNONYMS Catalog 


Column 
Name 
Type 


owner 
char(8) 
synonym 
char(l8) 
created 
date 
tabid 
integer 


Index 
Name 
Type 


synonym 
unique 
syntabid 
dupls 


Explanation 


user name of owner 
synonym identifier 
date synonym created 
table identifier 


Columns 


owner, synonym 
tabid 
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The SYSUSERS Catalog 


Column 
Name 


username 
usertype 


priority 
password 


Index 
Name 


users 


Type 


char(8) 
char(l) 


smallint 
char(8) 


Type 


unique 


Explanation 


user login identifier 
D = DBA, R = RESOURCE, 
C = CONNECT 
reserved for future use 
reserved for future use 


Columns 


username 


The SYSVIEWS Catalog 


Column 
Name 


tabid 
seqno 
text 


Index 
Name 


view 


Type 


integer 
smallint 
char(64) 


Type 


unique 


Explanation 


table identifier 
sequence number 
portion of SELECT statement 


Columns 


tabid, seqno 
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Environment Variables 


INFORMIX-ESQLlC makes the following assumptions about the 
user's environment: 


• 
The editor used is the predominant editor for the operating 
system (usually vi for UNIX systems and edlin for DOS 
systems). 


• 
The database worked with is in the current directory. 


• 
If the computer is running UNIX, the program that sends 
files to the printer is lp. If the computer is running DOS, 
the name of the printer device is lptl. 


• 
On UNIX systems, you use /tmp to store temporary files. 
On DOS systems, you use the current directory to store 
temporary files. 


• 
The INFORMIX-ESQL/C compiler and its associated files and 
libraries are located in /usr/informix (on a UNIX system) 
or \informix (on a DOS system). 
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Setting Environment Variables 


You can change any of the assumptions by setting one or more 
of the environment variables recognized by INFORMIX·ESQL/C. 
These environment variables are listed by operating system in 
later sections of this appendix. 


Setting Environment Variables on UNIX Systems 


You can set environment variables at the system prompt or in 
your .profile (Bourne shell) or .login (C shell) file. When you 
set an environment variable at the system prompt, you must 
reassign it the next time you log onto the system. When you 
set a variable in your .profile (Bourne shell) or .login (C shell) 
file, UNIX assigns it automatically every time you log onto the 
system. 


If you are using the Bourne shell, enter the following two 
commands to set the ABCD environment variable to value: 


ABCD=value 
export 
ABCD 


If you are using the C shell, enter the following command to set 
the ABCD environment variable to value: 


setenv 
ABCD value 


Setting Environment Variables on DOS Systems 


You can set environment variables at the system prompt or in 
your AUTOEXEC.BAT file. When you set an environment 
variable at the system prompt, you must reassign it the next 
time you start the system. When you set a variable in your 
AUTOEXEC.BAT file, DOS assigns it automatically every time 
you start the system. 
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Enter the following command to set the ABeD environment 
variable to value: 


set 
A8 CD=ualue 


UNIX Environment Variables 


The environment variables recognized by INFORMIX-ESQL/C are 
as follows: 


DBDATE 
specifies the format you want to use for 
DATE values. Through DBDATE, you can 
specify 


• 
The order of the month, day, and year in 
a date 


• 
Whether the year should be printed with 
two digits (Y2) or four digits (Y4) 


• 
The separator between the month, day, 
and year 


The default value for DBDATE is 


MDY41 


where M represents the month, 0 represents 
the day, Y4 represents a four-digit year, and 
the separator is a (I) slash (mm/dd/yyyy). 


Other acceptable values for the separator are 
a hyphen (-) or a period (.). The slash 
appears if you attempt to use any values 
other than the hyphen or period. 
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DBMONEY 


Suppose you want the date to appear in 
European format (dd-mm-yYYy). For the C 
shell, set the DBDATE environment variable 
as follows: 


setenv DBDATE DMY4- 


For the Bourne shell, use 


DBDATE=DMY4- 
export 
DBDATE 


applies to MONEY values. It has the format 


[frontJ(. I ,J(back] 


where front is the optional symbol that pre- 
cedes the MONEY value, the comma or the 
period is the optional symbol that separates 
the integral from the fractional part of the 
MONEY value, and back is the optional 
symbol that follows the MONEY value. The 
front and back symbols can be up to seven 
characters long and can contain any 
characters except commas or periods. 


The default value for DBMONEY is 


$. 


where the dollar sign precedes the MONEY 
value, and the period (.) separates the 
integral from the fractional part of the 
MONEY value. 


Suppose you want to represent MONEY 
values in Deutsche Marks. For the C shell, 
set the DBMONEY environment variable as 
follows: 


setenv DBMONEY DM, 
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DBPATH 


DBPRINT 


DBTEMP 


For the Bourne shell, use 


DBMONEY=DM, 
export 
DBMONEY 


where OM is the currency symbol, and the 
comma separates the integral from the 
fractional part of the MONEY value. 


specifies a list of directories for INFORMIX- 
ESQL/C to search for databases and assoCi- 
ated files. When looking for a database and 
related files, INFORMIX-ESQL/C first checks the 
current directory and then checks the 
directories specified in DBPATH. Use the 
same format that you use to set the PATH 
variable. 


specifies the print program for your com- 
puter. For most UNIX systems, the default 
program is lp. 


specifies the directory into which INFORMIX- 
ESQL/C places its temporary files. You need 
not set DBTEMP if /tmp is satisfactory. 


INFORMIXDIR 
specifies the directory containing the 
INFORMIX-ESQLlC files. 


c-, 


DOS Environment Variables 


The DOS environment variables recognized by IXFORMIX-ESQLlC 
are as follows: 


DBDATE 
specifies the format you want to use for 
DATE values. Through DBDATE. you can 
specify 


• 
The order of the month, day. and year in 
a date 


• 
Whether the year should be printed with 
two digits (Y2) or four digits (Y4) 


• 
The separator between the month. day, 
and year 


The default value for DBDATE is 


MDY41 


where M represents the month. 0 represents 
the day, Y4 represents a four-digit year, and 
the separator is a (I) slash (mm/dd/yyyy). 
Other acceptable values for the separator are 
a hyphen (-) or a period (.). The slash 
appears if you attempt to use any values 
other than the hyphen or period. 


Suppose you want the date to appear in 
European format (dd-mm-yyyy). Set the 
DBDATE environment variable as follows: 


set 
DBDATE=DMY4- 
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DBMONEY 


DBPATH 


applies to MONEY values. It has the format 


[front](. I ,](back] 


where front is the optional symbol that pre- 
cedes the MONEY value, the comma or the 
period is the optional symbol that separates 
the integral from the fractional part of the 
MONEY value, and back is the optional 
symbol that follows the MONEY value. The 
front and back symbols can be up. to seven 
characters long and can contain any 
characters except commas or periods. 


The default value for DBMONEY is 


$. 


where the dollar sign precedes the MONEY 
value, and the period separates the integral 
from the fractional part of the MONEY 
value. 


If you want to represent MONEY values in 
deutsche marks, for example, set the 
DBMONEY variable as follows 


set 
DBMONEY=DM, 


where DM is the currency symbol, and the 
comma separates the integral from the 
fractional part of the MONEY value. 


specifies a list of directories for INFORMIX- 
ESQL/C to search for databases and associ- 
ated files. When looking for a database and 
related files, INFORMIX-ESQL/C first checks the 
current directory and then checks the 
directories specified in DBPATH. 
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DBPRINT 


DBTEMP 


For example, if you want INFORMIX-ESQL/C to 
search for database files in Kevin's directory 
on C: and Debby's directory on D:, you can 
enter 


set DBPATH=c:\kevin;d:\debby 


(When you set the DBPATH variable, make 
sure you enter a semicolon between directory 
names.) 


Make sure you set the DBPATH variable 
before you execute the startsql command. 


specifies the name of the printer device. 
The default is lptl. To change the default 
to Ipt2, for example, you can enter 


set 
DBPRINT=lpt2 


specifies the directory where INFORMIX- 
ESQL/C should place its temporary files. 


INFORMIXDIR 
specifies the directory containing the 
INFORMIX-ESQL/C files. 
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The following words are INFORMIX-ESQL/C reserved words and 
cannot be used as program identifiers or database column 
names: 


ABSOLUTE 
ACCEPT 
ADD 
AFTER 
ALL 
ALTER 
AND 
ANY 
ARRAY 
AS 
ASC 
AT 
ATTRIBUTE 
AUDIT 
BEFORE 
BEGIN 
BETWEEN 
BY 
CHAR 
CHECK 
CLEAR 
CLIPPED 
CLOSE 
CLUSTER 
COLUMN 
COMMAND 
COMMENT 
COMMIT 
COMMITTED 
CONNECT 
CONSTRUCT 
CONTINUE 
CREATE 


CURRENT 
CURSOR 
DATABASE 
. DATE 
DBA 
DEC 
T 
DECIMAL 
DECLARE 
DEFAULTS 
DEFER 
DELETE 
DESC 
DESCRIBE 
DESCRIPTOR 
DIRTY 
DISPLAY 
DISTINCT 
DOUBLE 
DROP 
END 
ERROR 
EXCLUSIVE 
EXECUTE' 
EXISTS 
EXIT 
EXTENT 
EXTERN 
FETCH 
FIELD 
FILE 
FIRST 
FIXCHAR 
FLOAT 


FLUSH 
FOR 
FORM 
FREE 
FROM 
GRANT 
GROUP 
HAVING 
HELP 
IN 
INCLUDE 
INDEX 
INPUT 
INSERT 
INT 
INTEGER 
INTO 
IS 
ISOLATION 
KEY 
LAST 
LIKE 
LINE 
LOCK 
LOG 
LONG 
MATCHES 
MENU 
MESSAGE 
MODE 
MODIFY 
MONEY 
NAME 
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NEXT 
NO 
NOT 
NULL 
OF 
OFF 
ON 
OPEN 
OPTION 
OPTIONS 
OR 
ORDER 
OUTER 
PAGE 
PREPARE 
PREVIOUS 
PRIOR 
PRIVILEGES 
PROMPT 
PUBLIC 
PUT 
READ 
RECOVER 


RELATIVE 
RENAME 
REPEATABLE 
RESOURCE 
REVOKE 
ROLLBACK 
ROLLFORWARD 
ROW 
SCREEN 
SCROLL 
SECTION 
SELECT 
SERIAL 
SET 
SHARE 
SHORT 
SIZE 
SMALLFLOAT 
SMALLINT 
STABILITY 
START 
STATIC 
STATISTICS 


STRING 
STRUCT 
SUBSTRACT 
SYNONYM 
TABLE 
TEMP 
TO 
UNION 
UNIQUE 
UNLOCK 
UPDATE 
USING 
VALUES 
VIEW 
WAIT 
WCOLOR 
WHENEVER 
WHERE 
WITH 
WITHOUT 
WORK 
WRAP 
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The stores Database 


This appendix contains four sections. 


• 
The first section describes the structure of each table in the 
stores database, presents the RDSQL statement used to 
create each table, and notes any indexes on columns in each 
table. 


• 
The second section presents a map of the stores database 
with potential join columns identified. 


• 
The third section discusses the join columns that link the 
five tables in the database and presents figures illustrating 
these relationships. 


• 
The final section shows the data contained in each table in 
the stores database. 
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Structure of the Tables 


The stores database contains information about a fictitious 
sporting goods distributor that services stores in the Western 
United States. The database is made up of the following five 
tables: 


• 
customer 
• 
orders 
• 
items 
• 
stock 
• 
manufact 


customer 


The customer table contains information about 18 stores that 
order sporting goods from the distributor. This information 
includes the name of the store representative and the store 
name and address. The columns of the customer table are as 
follows: 


customer_ num 
fname 
Iname 
company 
address 1 
address2 
city 
state 
zipcode 
phone 


serial( 10 1) 
char( 15) 
char( 15) 
char(20) 
char(20) 
char(20) 
char( 15) 
char(2) 
char(5) 
char( 18) 


The customer_Dum column is indexed as unique. The 
zipcode column is indexed to allow duplicate values. 


orders 


The orders table contains information about orders placed by 
the distributor's customers. This information includes the 
order number, the date the order was made, the customer 
number, the shipping instructions, the customer's purchase 
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Appendix E 


The stores Database 
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The stores Database 


This appendix contains four sections. 


• 
The first section describes the structure of each table in the 
stores database, presents the RnSQL statement used to 
create each table, and notes any indexes on columns in each 
table. 


• 
The second section presents a map of the stores database 
with potential join columns identified. 


• 
The third section discusses the join columns that link the 
five tables in the database and presents figures illustrating 
these relationships. 


• 
The final section shows the data contained in each table in 
the stores database. 
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Structure of the Tables 


The stores database contains information about a fictitious 
sporting goods distributor that services stores in the Western 
United States. The database is made up of the following five 
tables: 


• 
customer 
• 
orders 
• 
items 
• 
stock 
• 
manufact 


customer 


The customer table contains information about 18 stores that 
order sporting goods from the distributor. This information 
includes the name of the store representative and the store 
name and address. The columns of the customer table are as 
follows: 


customer_num 
fname 
Iname 
company 
address1 
address2 
city 
state 
zipcode 
phone 


serial( 10 1) 
char( 15) 
char( 15) 
char(20) 
char(20) 
char(20) 
char( 15) 
char(2) 
char(5) 
char( 18) 


The customer_Dum column is indexed as unique. The 
zipcode column is indexed to allow duplicate values. 


orders 


The orders table contains information about orders placed by 
the distributor's customers. This information includes the 
order number, the date the order was made, the customer 
number, the shipping instructions, the customer's purchase 
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order number, the date the order was shipped, the weight of 
the order, the shipment charge, and the date the customer paid 
forthe order. It also tells whether or not a backlog exists. The 
columns of orders are as follows: 


order_num 
order_ date 
customer__ num 
ship_instruct 
backlog 
po_num 
ship_date 
ship_weight 
shiP._charge 
paid_date 


serial( 100 1) 
date 
integer 
char(40) 
char( 1) 
char( 10) 
date 
decimal(8,2) 
money(6) 
date 


The order_num column is indexed and must contain unique 
yalues: the customer 
num column is indexed but allows 
duplicates. 


items 


The items table keeps track of indiYidual items in an order. 
For example, some orders only contain one item, while other 
orders contain as many as fiye items. Information in the items 
table includes the item number, order number, stock number, 
manufacturer code. quantity, and the total price for each item 
ordered. The columns of the items table are as follows: 


item_num 
order 
num 
stock_.num 
manu 
code 
quantity 
total_price 


smailint 
integer 
smailint 
char(3) 
smallint 
money(8) 


The order_num column is indexed and allows duplicate 
yalues. A multiple-column index for the stock_num and 
manu_code columns also permits duplicate values. 
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stock 


The distributor offers customers 15 different types of sporting 
goods. For example, the distributor offers baseball gloves from 
three different manufacturers and basketballs from one 
manufacturer. 


The stock table is a catalog of the items sold by the 
distributor. For each item in stock, the stock table lists a 
stock number identifying the type of item. a code identifying 
the manufacturer. a description of the item. its unit price. the 
unit by which the item must be ordered. and a description of 
the unit (for example, a case containing 10 baseballs). 


The stock table contains the following columns: 


stock_num 
manu_code 
description 
unit 
price 
unit 
unit 
descr 


smallint 
char(3) 
char( 15) 
money(6) 
char(4) 
char( 15) 


A multiple-column index for the stock_num and 
manu_code columns allows only unique values. 


manufact 


The distributor handles sporting goods from five manu- 
facturers. Information about these manufacturers is kept in 
the manufact table. This information consists of an 
identification code and the manufacturer's name. The columns 
in the manufact table are as follows: 


manu_code 
manu 
name 
char(3) 
char( 15) 


The manu_code column is indexed and must contain unique 
values. 
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Join Columns that Link the Database 


The five tables of the stores database are linked together by 
join columns. This section identifies these columns and 
describes how you can use them to retrieve data from several 
tables at once and display it as if it were stored in a single 
table. Figures show the relationships among the tables and 
how information stored in one table supplements information 
in other tables. 


Join Columns in the customer and orders Tables 


The customer table and the orders table are joined by the 
customer_ num column, as shown in Figure E-l: 
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customer_num 
fname 
Iname 


customer table 
(detail) 


101 


102 


103 


104 


order 
num 


1001 


100:2 


100:3 


1004 


Ludwig 


Carole 


Philip 


Anthony 


06/01/1984 


06/,01/1984 


06/04/1984 


06/04/1984 


Pauli 


Sadler 


Currie 


Higgins 


104 


101 


104 


106 


orders table 
(detail) 


Figure E-l. Tables Joined by the customer_Dum Column 


For example, the customer table contains a customer_Dum 
column that holds a number identifying the customer, along 
with columns for the name, company, address, and telephone 
number. The row with information about Anthony Higgins 
contains the number 104 in the customer_Dum column. The 
orders table also contains a customer 
Dum column that 
stores the number of the customer who placed a particular 
order. According to Figure E-1, customer 104 (Anthony Hig- 
gins) has placed two orders, since his customer number appears 
in two rows of the orders table. 


The join relationship lets you select information from both 
tables. This means you can retrieve Anthony Higgins's name 
and address,and information about his orders at the same time. 
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Join Columns in the orders and items Tables 


The orders and items tables are linked by an order_Dum 
column that contains an identification number for each order. 
Ifa particular order includes several items, the same order 
number appears in several rows of the items table. Figure E-2 
shows this relationship. 


order_num 


1001 


1002 


1003 


item 
num 


2 


2 


3 


order 
date 


06/0111984 


06/01/1984 


06/04/1984 


1001 


1002 


1002 


1003 


1003 


1003 


customer_ num 


104 


101 


104 


stock 
num 


4 


3 


9 


8 


5 


orders table 
(detail) 


items table 
(detail) 


manu 
code 


HRO 


HSK 


HSK 


ANZ 


ANZ 


ANZ 


Figure E-2. Tables Joined by the order_Dum Column 
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Join Columns in the items and stock Tables 


The items table and the stock table are joined by two 
columns: the stock_num column stores a stock number for an 
item, and the manu_code column stores a code that identifies 
the manufacturer. You need both the stock number and the 
manufacturer code to uniquely identify an item. For example, 
the item with the stock number 1 and the manufacturer code 
HRO is a Hero baseball glove, while the item with the stock 
number 1 and the manufacturer code HSK is a Husky baseball 
glove. 
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The same stock number and manufacturer code can appear in 
more than one row of the items table if the same item belongs 
to separate orders, as shown in Figure E-3. 


items table 
(detail) 
item 
num 


2 


2 


3 


stock_num 


1 


1 


1001 


1002 


1002 


1003 


1003 


1003 


1004 


HRO 


HSK 


SMT 


4 


3 


9 


8 


5 


description 


baseball glove 


baseball glove 


baseball glove 


manu_code 


HRO 


HSK 


HSK 


ANZ 


ANZ 


ANZ 


HRO 


stock table 
(detail) 


Figure E-3. Tables Joined by Two Columns 
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Join Columns in the stock and manu/act Tables 


The stock table and the manufact table are joined by the 
manu_code column. The same manufacturer code can 
appear in more than one row of the stock table if the 
manufacturer produces more than one piece of equipment. 
This relationship is illustrated in Figure E-4. 


stock 
num 


1 


2 


manu_code 


NRG 


HSK 


HRO 


manu 
code 


HRO 


HSK 


SMT 


HRO 


manu 
name 


Norge 


Husky 


Hero 


description 


baseball glove 


baseball glove 


baseball glove 


baseball 


stock table 
(detail) 


manufact table 
(detail) 


Figure E-4. Tables Joined by the manu_code Column 


Joining lets you rearrange your view of a database whenever 
you want rearrange it. It provides flexibility that lets you 
create new relationships between tables without redesigning the 
database. You can easily expand the scope of a database by 
adding new tables that join the existing tables. As you read 
through this manual, you will see programs that set up the join 
relationships across tables of the stores database. You can 
refer to the preceding figures whene you need to review these 
relationships. 
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Data in the stores Database 


The data in the stores database is displayed in the tables that 
follow: 
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0/-'.... 
c.n 


customer Table 


customer - num 
fname 
Iname 
company 
address 1 
address2 
city 
state 
zipcode 
phone 


101 
Ludwig 
Pauli 
All Sports Supplies 
213 Erstwild Court 
Sunnyvale 
CA 
94086 
408-789-8075 


102 
Carole 
Sadler 
Sports Spol 
785 Geary St 
San Francisco 
CA 
94117 
415-822-1289 


103 
Philip 
Currie 
Phil's Sports 
654 Poplar 
P. 0. Box 3498 
Palo Alto 
CA 
94303 
415-328-4543 


104 
Anthony 
Higgins 
Play Ball! 
East Shopping Cntr. 
422 Bay Road 
Redwood City 
CA 
94026 
415-368-1100 


105 
Raymond 
Vector 
Los Altos Sports 
1899 La Lorna Drive 
Los Altos 
CA 
94022 
415-776-3249 


106 
George 
Watson 
Watson & Son 
1143 Carver Place 
Mountain View 
CA 
94063 
415-389-8789 


107 
Charles 
Ream 
Athletic Supplies 
41 Jordan Avenue 
Palo Alto 
CA 
94304 
415-356-9876 


108 
Donald 
Quinn 
Quinn's Sports 
587 Alvarado 
Redwood City 
CA 
94083 
415-544-8729 


109 
Jane 
Miller 
Sport Stull 
Mayfair Mart 
7345 Ross Blvd. 
Sunnyvale 
CA 
94086 
408-723-8789 


110 
Roy 
Jaeger 
AA Athletics 
520 Topaz Way 
Redwood City 
CA 
94062 
415-743-3611 


111 
Frances 
Keyes 
Sports Center 
3199 Sterling Court 
Sunnyvale 
CA 
94085 
408-277-7245 


112 
Margaret 
Lawson 
Runners & Others 
234 Wyandolle Way 
Los Altos Hills 
CA 
94022 
415-887-7235 


113 
Lana 
Beally 
Sportstown 
654 Oak Grove 
Menlo Park 
CA 
94025 
415-356-9982 


114 
Frank 
Albertson 
Sporting Place 
947 Waverly Place 
Redwood City 
CA 
94062 
415-886-6677 


115 
Alfred 
Grant 
Gold Medal Sports 
776 Gary Avenue 
Menlo Park 
CA 
94025 
415-356-1123 


116 
Jean 
Parmelee 
Olympic City 
1104 Spinosa Drive 
Mountain View 
CA 
94040 
415-534-8822 


117 
Arnold 
Sipes 
Kids Korner 
850 Lyllon Court 
Redwood City 
CA 
94063 
415-245-4578 


118 
Dick 
Baxter 
Blue Ribbon Sports 
5427 College 
Oakland 
CA 
94609 
415-655-0011 


o/-l 
..... 
0) 


>-3::r 
ro 
'"....c., 
I 
orders Table 
(l) 
'"t:l 
r» 
I 
order 
nurn order 
dAte customer 
num 
shIp 
instruct 
backlog 
po 
nllm 
ship 
date 
Ship 
weight 
Ship 
charge 
paid _ date 
.,... 
_. 
r»0- 
r» 
I 


Ul 
1001 
·06 0 I 
84 
104 
ups 
0 
B778:16 
06 05 84 
?O 40 
1000 
06.?? 84 


<t> 


1002 
06 01 
84 
101 
po on box: dellvp.r bACk door only 
0 
9?70 
06 06 84 
5060 
15:10 
07 0:1 84 


100:1 
06 04 84 
104 
via Upg 
0 
877890 
06 07 84 
:1560 
10RO 
06 
18 84 


1004 
06'04 84 
106 
nnQ bf!1I twice 
y 
R006 
95 80 
19 ?O 


1005 
06 04 84 
116 
call before delivering 
0 
2865 
06 08 84 
8080 
16 ?O 
06 2084 


1006 
06 04 84 
112 
after 10 am 
y 
Q iJ557 
70.80 
14?o. 


1007 
06 04 84 
117 
0 
27869:1 
0608 84 
12590 
2520 


1008 
06 04 84 
110 
closed Mooday 
y 
LZ230 
06 
27 84 
4560 
1:180 
07 
17 84 


1009 
06 04·84 
III 
door nexl to supersaver 
0 
4745 
06 
15 84 
20.40 
1000 
07 
21 
R4 


1010 
06 05 84 
115 
deliver 776 Gary ,f no answer 
0 
4?9Q 
06 07 84 
4060 
12.:10 
06 2? 84 


1011 
06 05 84 
104 
lipS 
0 
877897 
06 07 84 
1040 
500 
06 
18 84 


1012 
06'05 84 
117 
0 
278701 
06 09 84 
7080 
14?0 


101:1 
06 06 84 
104 
ViA ups 
0 
877930 
06 
11 
84 
60.80 
1220 
06 
21 ·84 


1014 
06 05 84 
106 
IIog bell. kick door loudly 
0 
8052 
06 09 84 
40.60 
12 :10 
07 
18 84 


1015 
06 06 84 
110 
closed Moo 
0 
MACO:l 
06 
II 
84 
2060 
6.:10 
06 
28 84 


items Table 


item- num 
order- num 
stock- num 
manu- code 
quantity 
total_price 


1 
1001 
1 
HRO 
1 
250.0 
1 
1002 
4 
H8K 
1 
960.0 
2 
1002 
3 
H8K 
1 
240.0 
1 
1003 
9 
ANZ 
1 
20.0 
2 
1003 
8 
ANZ 
1 
840.0 
3 
1003 
5 
ANZ 
5 
99.0 
1 
1004 
1 
HRO 
1 
960.0 
2 
1004 
2 
HRO 
1 
126.0 
3 
1004 
3 
H8K 
1 
240.0 
4 
1004 
1 
H8K 
1 
800.0 
1 
1005 
5 
NRG 
10 
280.0 
2 
1005 
5 
ANZ 
10 
198.0 
3 
1005 
6 
8MT 
1 
36.0 
4 
1005 
6 
ANZ 
1 
48.0 
1 
1006 
5 
8MT 
5 
125.0 
2 
1006 
5 
NRG 
5 
190.0 
3 
1006 
5 
ANZ 
5 
99.0 
4 
1006 
6 
8MT 
1 
36.0 
5 
1006 
6 
ANZ 
1 
48.0 
1 
1007 
1 
HRO 
1 
250.0 
2 
1007 
2 
HRO 
1 
126.0 
3 
1007 
3 
H8K 
1 
240.0 
4 
1007 
4 
HRO 
1 
480.0 
5 
1007 
7 
HRO 
1 
600.0 
1 
1008 
8 
ANZ 
1 
840.0 
2 
1008 
9 
ANZ 
5 
100.0 
1 
1009 
1 
8MT 
1 
450.0 
1 
1010 
6 
8MT 
1 
36.0 
2 
1010 
6 
ANZ 
1 
48.0 
1 
1011 
5 
ANZ 
5 
99.0 
1 
1012 
8 
ANZ 
1 
840.0 
2 
1012 
9 
ANZ 
10 
200.0 
1 
1013 
5 
ANZ 
1 
19.8 
2 
1013 
6 
8MT 
1 
36.0 
3 
1013 
6 
ANZ 
1 
48.0 
4 
1013 
9 
ANZ 
2 
40.0 
1 
1014 
4 
H8K 
1 
960.0 
2 
1014 
4 
HRO 
1 
480.0 
1 
1015 
1 
8MT 
1 
450.0 
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stock table 


stock 
num 
manu- 
code 
description 
unit_price 
unit 
unit- descr 


HRC 
baseball gloves 
250.00 
case 
10 gloves / case 


HSK 
baseball gloves 
800.00 
case 
10 gloves/case 


SMT 
baseball gloves 
450.00 
case 
10 gloves/case 


2 
HRC 
baseball 
126.00 
case 
24/case 


3 
HSK 
baseball bat 
240.00 
case 
12/case 


4 
HSK 
football 
960.00 
case 
24/case 


4 
HRC 
football 
480.00 
case 
24/case 


5 
NRG 
tennis racquet 
28.00 
each 
each 


5 
SMT 
tennis racquet 
25.00 
each 
each 


5 
ANZ 
tennis racquet 
19.80 
each 
each 


6 
SMT 
tennis ball 
36.00 
case 
24 cans / case 


6 
ANZ 
tennis ball 
48.00 
case 
24 cans / case 


7 
HRC 
basketball 
600.00 
case 
24/case 


8 
ANZ 
volleyball 
840.00 
case 
24/case 


9 
ANZ 
volleyball net 
20.00 
each 
each 


manufact Table 


manu 
code 
manu 
name 


ANZ 
Anza 


HSK 
Husky 


HRC 
Hero 


NRG 
Norge 


SMT 
Smith 
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Appendix F 


The bcheck Utility 
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The beheck Utility 


The bcheck program is a C·ISAM utility program that checks 
and repairs C·ISAM index files. It is distributed with INFORMIX· 
ESQL/C. 


bcheck compares an index (.idx) file to a data (.dat) file to see 
if the two are consistent. If they are not, bcheck asks whether 
you want to delete and rebuild the corrupted indexes. 


When running bcheck from the operating system command 
line, you must specify the table name used by the INFORMIX· 
ESQL/C system catalogs. For example, the customer table in 
the stores database is identified in the system catalogs as 
customelOO (on UNIX systems) or custolOO (on DOS 
systems) and not as customer. 


You can list the contents of the database directory to 
determine the appropriate table name. 


In the following example, bcheck is run from the command 
line on the customer file and finds no errors. 


bcheck -n customel00 


SCHECK 
C-ISAM S-tree Checker version 3.00.00 
Copyright 
(C) 
1981-1986 Relational 
Database Systems, 
Inc. 
Software Serial 
Numbar 
RDS#ROOOOOO 


C-ISAM Fi Ie: 
customel00 


Checking dictionary and file sizes. 
Index 
fi Ie node size = 1024 
Current C__ISAM index fi la node size = 1024 
Checking data file records. 
Checking 
indexes and key descriptions. 
Index 
1 = unique key 
o index node(s) 
used -- 1 index b-tree level(s) 
used 
Index 2 = unique key 
(0,4,2) 
1 index node(s) 
used -- 1 index b-tree level(s) 
used 
Index 3 = duplicates 
(111,5,0) 
1 index node(s) 
used -- 1 index b-tree level(s) 
used 
Checking data 
record and 
index node free lists. 
4 
index node(s) 
used, 
0 free -- 18 data record(s) 
used, 
4 free 
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For each index, bcheck prints a group of up to eight numbers. 
These numbers indicate the position of the key in each record. 


You can also use beheck with the following options: 


-i 
Check index file only 
-1 
List entries in B+ trees 
-n 
Answer no to all questions 
-y 
Answer yes to all questions 
-q 
Suppress printing of the program banner 
-s 
Resize the index file node size 


The bcheck command syntax is as follows: 


beheck -Ii I 1 I yin I q I s] file-name 


Unless you use the -n or -y option, bcheck is interactive, 
waiting for you to respond to each error it finds. 


Use the -y option with caution. Do not run bcheck using the 
-y option if you are checking the files for the first time. 
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Here is a sample run in which bcheck finds errors. The-n 
option is selected, so that each question bcheck asks is 
automatically answered "no." 


SCHECK 
C-ISAM B-tree Checker version 3.00.00 
Copyright 
(C) 
1981-1986 Relational Database Systems, 
Inc. 
Software Serial 
Number 
RDS#ROOOOOO 


C-ISAM Fi Ie: 
customel00 


Checking dictionary and file sizes. 
Index file node size = 
1024 
Current 
C_ISAM index Ii Ie noda size = 1024 
Checking data Ii la records. 
Checking 
indexes and key descriptions. 
Index 
1 = unique kay 
o index node(s) 
used - 
1 index b-tree level(s) 
used 


ERROR: 
3 bad data 
record(s) 
Delete 
index 
? 
no 


Index 2 = unique key 
(0,4,2) 
1 index node(s) used-l 
index b-trea level(s) 
used 


ERROR: 
3 bad data 
record(s) 
Delete 
index 
? 
no 


Index 3 = duplicates 
(111,5,0) 
1 index node(s) 
used - 
1 index b-tree leval(s) 
used 


ERROR: 
3 bad data 
record(s) 
Delete. index 
? 
no 


Checking data record and 
index node frea lists. 


ERROR: 
3 missing data record(s) 
Fix data 
record free list 
? no 


4 
index node(s) 
used, 
0 free 
18 data record(s) 
used, 
4 Irre 
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Since beheck finds errors, you must delete and rebuild the 
corrupted indexes. The -y option is used to answer "yes" to all 
questions asked by bcheck: 


BCHECK 
C-ISAM B-tree Checker version 3.00.00 
Copyright 
(C) 
1981-1986 Relational 
Database Systems, 
Inc. 
Software Serial 
Number 
RDS#ROOOOOO 


C-ISAM Fi Ie: 
custome100 


Checking dictionary and file sizes. 
Checking data file 
records. 
Checking 
indexes and key descriptions. 
Index 
1 = 
unique key 
1 index node(s) 
used - 
1 index b-tree level(s) 
used 


ERROR: 
3 bad data 
record(s) 
Delete 
index 
? yes 


Remake 
index? yes 
Index 
2 = unique key 
(0,4,2) 
1 index node(s) 
used - 
1 index b-tree level(s) 
used 


ERROR: 
3 bad data 
record(s) 
Delete 
index 
? yes 


Remake 
index? yes 


Index 3 = 
dupl icates 
(111,5,0) 
1 index node(s) 
used - 
1 index b-tree level(s) 
used 


ERROR: 
3 bad data 
record(s) 
Delete 
index 
? yes 


Remake index? yes 


Checking data 
record and 
index node free lists. 


ERROR: 
3 missing data 
record(s) 
Fix data 
record free 
list 
? yes 


Recreate data 
record 
free list 
Recreate 
index 3 
Recreate 
index 2 
Recreate 
index 
1 


4 
index node(s) 
used, 
0 free - 
18 data 
record(s) 
used, 
4 free 
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The sqlconv Utility 
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The sqlconv Utility 


The sqlconv utility is provided for the Database Administrator 
who wants to use INFORMIX-SQL, INFORMIX-ESQL/C, or 
INFORMIX-4GL with an existing INFORMIX database (Version 3.0 
or higher). From the INFORMIX database, sqlconv aids a user 
in creating a new RDSQL -compatible database. It leaves the old 
database intact. 


This appendix discusses the steps necessary to convert an 
INFORMIX database to an RDSQL -compatible database. The 
new database can be used with INFORMIX-SQL, INFORMIX-ESQL/C, 
or INFORMIX-4GL on either DOS or UNIX systems. The 
appendix is divided into the following sections: 


• 
INFORMIX-SQL Conversion Procedures 
• 
INFORMIX-ESQL/C Conversion Procedures 
• 
INFORMIX-4GL Conversion Procedures 


Each section describes two methods you can use to accomplish 
the conversion. The method you should use depends on the 
disk space constraints of your system. 


Caution! sqlconv will not convert INFORMIX database permissions. 
You must grant new permissions on tables and fields after your new 


INFORMIX-SQL database has been created and loaded. 


RDSQL reserved words are not the same as INFORMIX reserved words. 
If you receive a syntax error while running your new CREATE 
scripts or INFORMIX-ESQLlC or INFORMIX-4GL programs, make sure your 
TABLE and FIELD names are not among the new reserved words. 
For a list of reserved words, see the appendix "Reserved Words" in 
this manual. 


Make sure all INFORMIX composite fields are indexed. INFORMIX-SQL 
takes no action on unindexed composite fields. Indexed composite 
fields will have composite indexes created for them. 


If you have used the LOCATION option to spread an INFORMIX 
database across a number of directories, converting the database 
using sqlconv places all of these files in the new .dbs directory. 


You cannot specify a new starting number for a serial field. 
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INFORMIX-SQL Conversion Procedures 


If There Is No Shortage of Disk Space 


You can convert an entire INFORMIX database to an 
INFORMIX-SQL database at one time if there is no shortage 
of disk space. 


To convert an entire database at once, you must have available 
on the disk at least three times the amount of space required 
by all the tables in the database plus additional space for the 
INFORMIX-SQL system files. The following steps outline the 
process of converting an entire database at once: 
1. 
Make certain that INFORMIX and INFORMIX-SQL are 
included in your search path. On DOS systems, INFORMIX 
and INFORMIX-SQL must be installed in the same directory. 


2. 
Set the INFORMIXDIR environment variable to point 
to the INFORMIX-SQL directory. 


3. 
Change your current directory to the directory that 
contains your INFORMIX database. 


4. 
Create a backup copy of the INFORMIX database. 


5. 
Enter 


sqlconv databasename 


where databasename is the name of the INFORMIX 
database you want to convert. Do not include a filename 
extension. This command generates an INFORMER script 
file (indicated by a .uId extension) and an INFORMIX-SQL 
script file (indicated by a .sqI extension). 
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6. 
Enter 


informer databasename databasename.uld 


This command unloads the database files (in ASCII 
format) to unload files (indicated by a .unl extension) 
for each table in the database. 


7. 
Enter 


isql - databasename.sql 


This command re-creates the database, tables, and 
indexes in RDSQL format and loads the data from the .unl 
files (generated by informer) into the appropriate tables. 


8. 
The final step in the conversion procedure is to remove 
all the old database files, the .uld files, the .sql files, and 
the .unl files, from your directory. Do not remove your 
forms and reports. You can update these later. 


If There Is a Shortage of Disk Space 


The following method is more economical in terms of disk 
space, but it is a more involved and time-consuming process 
than the method discussed in the previous section. Use this 
method if you do not have at least three times the amount of 
space required by the database. 


The following steps outline the conversion of the sample 
INFORMIX database, payroll, to an INFORMIX-SQL database: 


1. 
Make certain that INFORMIX and INFORMIX-SQL are 
included in your search path. On DOS systems, INFORMIX 
and INFORMIX-SQL must be installed in the same directory. 


2. 
Set the INFORMIXDIR environment variable to point 
to the INFORMIX-SQL directory. 


3. 
Change your current directory to the directory that 
contains your INFORMIX database. 
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4. 
Create a backup copy of the INFORMIX database. 


5. 
Enter 


sqlconv payroll 


Do not include a filename extension. This command 
generates the .uld and .sql scripts necessary to convert 
the database. 


6. 
Create a copy of the payroll.sql file, and make sure you 
include the .sql extension to the filename of the new file. 
In this instance, we have named this file createp.sql. 


7. 
Edit the createp.sql file using your system editor, 
and remove all the load statements from the file. The 
CREATE DATABASE, CREATE TABLE, and CREATE 
INDEX statements should be the only statements 
remaining in the file. Exit the file. 


8. 
Enter 


isql . createp.sql 


This command creates the INFORMIX-SQL database and 
its tables and indexes, but it does not load the data. 


9. 
On UNIX systems, enter 


cat payroll.uld 


On DOS systems, enter 


type payroll.uld 


The statements in the payroll.uld file outline the first 
steps of the conversion operation. You must execute each 
of these statements separately. You may find it helpful to 
print a copy of the payroll.uld file for easy reference. 
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10. 
Enter 


informer payroll 


At the INFORMER prompt, enter the first line of the 
payroll.uld file exactly as it appears. This creates the 
unload file for the first table. Exit INFORMER. 


11. 
On UNIX systems, locate the first load statement in the 
payroll.sql file by entering 


cat payroll.sql 


On DOS systems, locate the first load statement in the 
payroll.sql file by entering 


type payroll.sql 


12. 
Enter 


isql payroll . 


At the> prompt, enter the first load statement that 
appears in the payroll.sql file. Exit to the operating 
system. 


13. 
Before you can perform the same operations on any other 
database tables, you must free additional disk space by 
erasing the INFORMIX versions of the recently created 
INFORMIX-SQL files. To erase these files, enter 


dbstatus payroll 


14. 
At the dbstatus prompt, enter 


erase file filename 


where filename is the name of the file referred to in 
Step 12. Exit dbstatus. 
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15. 
On UNIX systems, erase the unload file by entering from 
the command line 


rm filename.unl 


On DOS systems; erase the unload file by entering from 
the command line 


erase filename.unl 


16. 
Continue to unload each table, one at a time, from the 
INFORMIX database and then load it into the INFORMIX-SQL 
database. Do this by repeating Steps 10 through 15 until 
all load statements in the payroll.sql file have been 
executed. This operation loads the actual data into the 
newly created database. 


17. 
When all tables in the database have been converted, 
erase the .sql files and the .uld files, and drop the 
INFORMIX database. 


18. 
You can check to see if your database has been success- 
fully converted to INFORMIX-SQL by entering 


isql payroll 


If the database has been successfully converted, the 
INFORMIX-SQL Main Menu appears with the database 
name on the information line. To see if the tables have 
been successfully converted, choose the New option from 
the Query-language option on the Main Menu. Enter 


select • from tablename 


Data that has been loaded successfully into the table 
appears on your screen. 


Caution! You cannot rerun sqlconv after you have erased a table. 
The new scripts generated by the command do not contain the 
information necessary to convert the table. 
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INFORMIX-ESQLIC Conversion Procedures 


If There Is No Shortage of Disk Space 


You can convert an entire INFORMIX database to an RDSQL 
-compatible database for use with INFORMIX-ESQL/C at one time 
if there is no shortage of disk space. 


To convert an entire database at once, you must have available 
on the disk at least three times the amount of space required 
by all the tables in the database plus additional space for the 
INFORMIX-ESQL/C system files. The following steps outline the 
process of converting an entire database at once: 


1. 
Make certain that INFORMIX and INFORMIX-ESQL/C are 
included in your search path. On DOS systems, INFORMIX 
and INFORMIX-ESQL/C must be installed in the same 
directory. 


2. 
Set the INFORMIXDIR environment variable 
to point to the INFORMIX-ESQL/C directory. 


3. 
Change your current directory to the directory that 
contains your INFORMIX database. 


4. 
Create a backup copy of the INFORMIX database. 


5. 
Enter 


sqlconv -e databasename 


where databasename is the name of the INFORMIX 
database you want to convert. Do not include a filename 
extension. This command generates an INFORMER script 
file (indicated by a .uld extension), an INFORMIX-ESQL/C 
program (indicated by a .ec extension), and a dbload 
command file (indicated by a .cmd extension). 
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6. 
Enter 


informer databasename databasename.uld 


This command unloads the database files (in ASCII 
format) to unload files (indicated by a .unl extension) 
for each table in the database. 


7. 
Enter 


esql databasename.ec -0 databasename.out 


This command compiles the INFORMIX-ESQL/C program 
created in Step 5, and creates a .c file (a C program) and 
a .out executable file. 


8. 
Enter 


databasename.out 


This command runs the INFORMIX-ESQL/C program that 
you compiled in Step 7 and re-creates the database, 
tables, and indexes in RDSQL format. 


9. 
Enter 


dbload -d databasename -c databasename.cmd -I errlog 


This command loads the data from the .unl files 
(generated by informer) into the appropriate tables and 
creates an errlog file, which contains diagnostic informa- 
tion about any rows that were not successfully loaded. 
For more information on dbload, see the appendix 
"The dbload Utility" in this manual. 


10. 
The final step in the conversion procedure is to remove 
all the old database files, the .uld, .ec, .cmd, .unl, .c, and 
.out files from your directory. Do not remove your forms 
and reports. You can update these later. 
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If There Is a Shortage of Disk Space 


The following method is more economical in terms of disk 
space, but it is a more involved and time-consuming process 
than the method discussed in the previous section. Use this 
method if you do not have at least three times the amount of 
space required by the database. 


The following steps outline the conversion of the sample 
INFORMIX database, payroll, to an RDSQL -compatible database 
for use with INFORMIX-ESQL/C: 


1. 
Make certain that INFORMIX and INFORMIX-ESQL/C are 
included in your search path. On DOS systems, INFORMIX 
and INFORMIX-ESQL/C must be installed in the same 
directory. 


2. 
Set the INFORMIXDIR environment variable to point 
to the INFORMIX-ESQL/Cdirectory. 


3. 
Change your current directory to the directory that 
contains your INFORMIX database. 


4. 
Create a backup copy of the INFORMIX database. 


5. 
Enter 


sqlconv -e payroll 


Do not include a filename extension. This command 
generates an INFORMER script file (indicated by a .uld 
extension), an INFORMIX-ESQL/C program (indicated by a 
.ec extension), and a dbload command file (indicated by 
a .cmd extension). 


6. 
Enter 


esql payroll.ec -0 payroll.out 


This command compiles the INFORMIX-ESQL/C program 
you created in Step 5 and creates a .c file (a C program) 
and a .out executable file. 
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7. 
Enter 


payroll.out 


This command runs the INFORMIX-ESQL/C program you 
compiled in Step 6 and re-creates the database, tables, 
and indexes in RDSQL format, but it does not load the 
data. 


8. 
On UNIX systems, enter 


cat payroll.uld 


On DOS systems, enter 


type payroll.uld 


The statements in the payroll.uld file outline the first 
steps of the conversion operation. You must execute each 
of these statements separately. You may find it helpful to 
print a copy of the payroll.uld file for easy reference. 


9. 
Enter 


informer payroll 


At the INFORMER prompt, enter the first line of the 
payroll.uld file exactly as it appears. This creates the 
unload file for the first table. Exit INFORMER. 


10. 
The .crnd file describes the form of the data and contains 
the INSERT INTO statements indicating how this data is 
to be placed in the database files. The INSERT INTO 
statements are necessary to load the data into the newly 
created database. You must execute each of the state- 
ments separately. To do this, create a copy of the 
payroll.cmd file for each INSERT INTO statement and 
make sure you include the .crnd extension to the filename 
of each new file. In this instance, we have named the files 
one.crnd and two.crnd. 
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11. 
Edit the one.cmd file using your system editor, and 
remove all but the first INSERT INTO statement from 
the file. Exit the file. 


12. 
Execute the first INSERT INTO statement in the 
one.cmd file by entering 


dbload -d payroll -c one.cmd -I errlog 


This command loads the data from the .unl file into 
the appropriate table and creates an errlog file, which 
contains diagnostic information about any rows that were 
not successfully loaded. A statement appears on the 
screen indicating how many rows were loaded into the 
file. For more information on dbload, see the appendix 
"The dbload Utility" in this manual. 


13. 
Before you can perform the same operations on any other 
database tables, you must free additional disk space by 
erasing the INFORMIX versions of the recently created 
INFORMIX-ESQL/C files. To erase these files, enter 


dbstatus payroll 


14. 
At the dbstatus prompt, enter 


erase file filename 


where filename is the name of the file referred to in the 
.cmd file created in Step 11. Exit dbstatus. 


15. 
On UNIX systems, erase the unload file for this same file 
by entering from the command line 


rm filename.unl 


On DOS systems, erase the unload file for this same file 
by entering from the command line 


erase filename.unl 
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16. 
Continue to unload each table, one at a time, from the 
INFORMIX database and then load it into the INFORMIX- 


ESQL/C database. Do this by repeating Steps 9 through 
15. Remember to make a copy of the .emd file for each 
INSERT INTO statement it contains. Each copy must 
have a unique name and must end in the .emd extension. 
The correct filename must be included on the command 
line each time you run the dbload command. 


Repeat these steps until all load statements in the 
payroll.emd file have been executed. This operation 
loads the actual data into the newly created database. 


17. 
Check the contents of the data files in the newly created 
INFORMIX-ESQLlC database to make sure you have success- 
fully converted your INFORMIX database. 


18. 
When all tables in the database have been converted, 
erase the .uld, .ee, .emd, .e, and .out files, and drop the 
INFORMIX database. 


Caution! You cannot rerun sqlconv after you have erased a table. 
The new scripts generated by the command do not contain the infor- 
mation necessary to convert the table. 
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INFORMIX-4GL Conversion Procedures 


If There Is No Shortage of Disk Space 


You can convert an entire INFORMIX database to an RDSQL 
-compatible database for use with INFORMIX-4GL at one time 
if there is no shortage of disk space. 


To convert an entire database at once, you must have available 
on the disk at least three times the amount of space required 
by all the tables in the database plus additional space for the 
INFORMIX-4GL system files. The following steps outline the 
process of converting an entire database at once: 


1. 
Make certain that INFORMIX and INFORMIX-4GL are 
included in your search path. On DOS systems, INFORMIX 
and INFORMIX-4GL must be installed in the same directory. 


2. 
Set the INFORMIXDIR environment variable to point 
to the INFORMIX·4GL directory. 


3. 
Change your current directory to the directory that 
contains your INFORMIX database. 


4. 
Create a backup copy of the INFORMIX database. 


5. 
Enter 


sqlconv -4 databasename 


where databasename is the name of the INFORMIX 
database you want to convert. Do not include a filename 
extension. This command generates an INFORMER script 
file (indicated by a .uld extension), an INFORMIX·4GL 
program (indicated by a .4g1 extension), and a dbload 
command file (indiCated by a .cmd extension). 
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6. 
Enter 


informer databasename databasename.uld 


This command unloads the database files (in ASCII 
format) to unload files (indicated by a .unl extension) 
for each table in the database. 


7. 
Enter 


c4g1 databasename.4g1 -0 databasename.4ge 


This command compiles the INFORMIX-4GL program 
created in Step 5, and creates a .c file, a .ec file 
(C programs), and a Age executable file. 


8. 
Enter 


databasename.4ge 


This command runs the INFORMIX·4GL program you 
compiled in Step 7 and re-creates the database, tables, 
and indexes in RDSQL format. 


9. 
Enter 


dbload -d databasename -c databasename.cmd -I errlog 


This command loads the data from the .unl files 
(generated by informer) into the appropriate tables and 
creates an errlog file, which contains diagnostic informa- 
tion about any rows that were not successfully loaded. 
For more information on dbload, see the appendix 
"The dbload Utility" in this manual. 


10. 
The final step in the conversion procedure is to remove 
all the old database files, the .uld, .4gl, Age, .ec, .cmd, 
.unl, and .c files from your directory. Do not remove 
your forms and reports. You can update these later. 
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If There Is a Shortage of Disk Space 


The following method is more economical in terms of disk 
space, but it is a more involved and time-consuming process 
than the method discussed in the previous section. Use this 
method if you do not have at least three times the amount 
of space required by the database. 


The following steps outline the conversion of the sample 
INFORMIX database, payroll, to an RDSQL -compatible 
database for use with INFORMIX-4GL 


1. 
Make certain that INFORMIX and INFORMIX-4GL are 
included in your search path. On DOS systems, INFORMIX 
and INFORMIX-4GL must be installed in the same directory. 


2. 
Set the INFORMIXDIR environment variable to point 
to the INFORMIX-4GL directory. 


3. 
Change your current directory to the directory that 
contains your INFORMIX database. 


4. 
Create a backup copy of the INFORMIX database. 


5. 
Enter 


sqlconv -4 payroll 


Do not include a filename extension. This command 
generates an INFORMER script file (indicated by a .uld 
extension), an INFORMIX-4GL program (indicated by a 
AgI 
extension), and a dbload command file (indicated 
by a .cmd extension). 


6. 
Enter 


c4g1 payroll.4gl -0 payroll.4ge 


This command compiles the INFORMIX·4GL program 
you created in Step 5 and creates a .c file, a .ec file 
(C programs), and a Age executable file. 
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7. 
Enter 


payrol1.4ge 


This command runs the INFORMIX-4GL program you 
compiled in Step 6 and re-creates the database, tables, 
and indexes in RDSQL format, but it does not load the 
data. 


8. 
On UNIX systems, enter 


cat payroll.uld 


On DOS systems, enter 


type payroll.uld 


The statements in the payroll.uld file outline the first 
steps of the conversion operation. You must execute each 
of these statements separately. You may find it helpful to 
print a copy of the payroll.uld file for easy reference. 


9. 
Enter 


informer payroll 


At the INFORMER prompt, enter the first line of the 
payroll.uld file exactly as it appears. This creates the 
unload file for the first table. Exit INFORMER. 


10. 
The .cmd file describes the form of the data and contains 
the INSERT INTO statements indicating how this data is 
to be placed in the database files. The INSERT INTO 
statements are necessary to load the data into the newly 
created database. You must execute each of the state- 
ments separately. To do this, create a copy of the 
payroll.cmd file for each INSERT INTO statement and 
make sure you include the .cmd extension to the filename 
of each new file. In this instance, we have named the files 
one.cmd and two.cmd. 
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11. 
Edit the one.cmd file using your system editor, and 
remove all but the first INSERT INTO statement from 
the file. Exit the file. 


12. 
Execute the first INSERT INTO statement in the 
one.cmd file by entering 


dbload -d payroll -c one.cmd -I errlog 


This command loads the data from the .unl file into 
the appropriate table and creates an errlog file, which 
contains diagnostic information about any rows that were 
not successfully loaded. A statement appears on the 
screen indicating how many rows were loaded into the 
file. For more information on dbload, see the appendix 
"The dbload Utility" in this manual. 


13. 
Before you can perform the same operations on any other 
database tables, you must free additional disk space by 
erasing the INFORMIX versions of the recently created 
INFORMIX-4GL files. To erase these files, enter 


dbstatus payroll 


14. 
At the dbstatus prompt, enter 


erase file filename 


where filename is the name of the file referred to in the 
.cmd file created in Step 11. Exit dbstatus. 


15. 
On UNIX systems, erase the unload file for this same file 
by entering from the command line 


rm filename.unl 


On DOS systems, erase the unload file for this same file 
by entering from the command line 


erase filename.unl 
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16. 
Continue to unload each table, one at a time, from the 
INFORMIX database and then load it into the INFORMIX-4GL 
database. Do this by repeating Steps 9 through 15. 
Remember to make a copy of the .emd file for each 
INSERT INTO statement it contains. Each copy must 
have a unique name and must end in the .emd extension. 
The correct filename must be included on the command 
line each time you run the dbload command. 


Repeat these steps until all load statements in the 
payroll.emd file have been executed. This operation 
loads the actual data into the newly created database. 


17. 
Check the contents of the data files in the newly created 
INFORMIX·4GL database to make sure you have success- 
fully converted your INFORMIX database. 


18. 
When all tables in the database have been converted, 
erase the .uId, .ee, .cmd, .e, AgI, and Age files, and 
drop the INFORMIX database. 


Caution! You cannot rerun sqlconv after you have erased a table. 
The new scripts generated by the command do not contain the infor- 
mation necessary to convert the table. 
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Overview 


Several significant changes have occurred in RDSQL in the 
transition from Version 1.1 to Version 2.0 and higher. These 
changes include an increase in the number of system catalogs, 
slight changes to their content (see Appendix B), and the intro- 
duction of NULL values. 


Version 2.1 of INFORMIX-SQL and INFORMIX-ESQL/C and Version 
1.1 of INFORMIX-4GL use the 2.1 Version of RDSQL. You cannot 
use databases constructed under Version 1.1 with the Version 
2.1 products or with INFORMIX-4GL unless you modify the old 
databases with the dbupdate utility. 


Using dbupdate 


To convert your old databases to Version 2.1, execute the 
following command: 


dbupdate [-b I -n] old-database-name new-database-name 


dbupdate creates a new Version 2.1 database in the current 
directory with the name new-database-name, and copies the 
data from the old system catalogs to the new system catalogs, 
making the appropriate changes. 


If you do not use the -b or -n option, dbupdate converts the 
value of all CHAR type columns with blank data to NULL and, 
for each numeric column, asks you if it should convert zero 
values to NULL values. 


The -b option causes dbupdate to leave blank data in CHAR 
columns as blanks. The -n option alters the system catalogs to 
define all columns as NOT NULL and does not touch the data 
files. The -n option includes the -b option. 
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In addition to these changes, dbupdate corrects a bug in the 
representation of negative DECIMAL values. 


When dbupdate finishes, you have two database directories 
(the new and the old) with two separate system catalogs, but 
the data and index files are shared (linked). To complete the 
update, remove the old database directory. 


Caution! When you execute the dbupdate command on DOS sys- 
tems, it loads the database agent. Be certain that the database agent 
is not already loaded in memory when you execute this command. 


To find out if the database agent is loaded, enter set from the com- 
mand line. This displays a list of your environment variables. If the 
database agent is loaded, the variable sqlcaddr is listed. If sqlcaddr 
is listed, you must unload the database agent using the exit com- 
mand before you run dbupdate. 


No NULL Databases 


You may want to avoid working with NULL values. You can do 
this if you carefully adhere to the following rules: 


• 
When converting Version 1.1 databases, select the -n 
option of dbupdate. 


• 
When creating new tables, define all columns as NOT 
NULL. 


• 
In all form specification files, add the WITHOUT NULL 
INPUT clause in the DATABASE section. 


• 
In form specification files, specify all formonly fields as 
NOT NULL. 


These last two rules mean you must recompile all your old form 
specification files. 
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The dbload Utility 


The dbload utility provides a method for transferring 
information (raw data existing in ASCII form) from an 
operating-system file into an RDSQL database. It allows for the 
easy and efficient transfer of database files created for other 
RDSQL databases-or created on an entirely different database 
system-to your RDSQL database. Error logging provides diag- 
nostic information about rows that could not be loaded. 


When running dbload, you have the option of specifying the 
point at which each N number of rows is committed to the 
database-or of aborting the entire process and making no 
changes to the database. 


These are the primary features of dbload: 


• 
Data from one or more system files can be loaded into one 
or more database tables. 


• 
Rows that cannot be loaded into the database are trapped 
and placed (with diagnostic information) into a user- 
specified file. 


• 
Loading continues until a user-specified total number of 
rows cannot be entered into the database. 


• 
The loading process can be optionally terminated without 
making changes to the existing database. 


• 
Loading can begin at a specified line in the system file. 


• 
Selected fields or columns can be loaded from the system 
file and entered in specified columns of a table. 


• 
Both fixed-length and variable-length data files can be 
loaded. 


• 
NULL values can be indicated, and a different indicator can 
be used with each field. 
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• 
Constants (values not in the system file) can be entered into 
the database file. 


To use dbload, create a command file that tells dbload what 
actions you·want carried out. 


This command file 


• 
Describes the form of the data in the system files 


• 
Contains one or more RDSQL INSERT INTO statements 
indicating how this data is to be placed into the selected 
database files 


You invoke dbload from the operating system command line 
by indicating (at a minimum) the name of the dbload program 
and an option. If you provide no additional information on the 
command line, dbload prompts you for the information (data- 
base name, command filename, and error-log filename) it must 
have to run. 


The syntax of the basic dbload command is as follows: 


dbload : -d dbname I -c comfile I -I errlog : ... 


-d dbname is the name of the RDSQL database that receives the 
new information. 


-c comfile 
is the name of the command file that contains the 
dbload command statements. 


-I errlog 
is the name of the file that receives the 
error-logging information. 
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dbload can be used with several options. Options must be 
placed on the command line. The following options are 
available: 
. 


-s 
instructs dbload to perform a syntax check on the 
command file only and load no data. The command 
file is displayed on the screen, and errors are indi- 
cated where they are found. You can redirect this 
output to a system file with the > redirect symbol. 


Normally, you should run dbload with the -s option 
in advance of actually loading the data. 


-n num 
prompts dbload to display a message when each set 
of num rows is loaded into the database. 


For databases with transactions, the -n num indicates 
the number of rows that must be successfully read by 
dbload before being committed to the database. 
Until this number is reached, no rows are committed 
to the database. The default is 100 rows. 


-e num 
indicates the total number of bad rows processed 
before dbload aborts the program. The default is 10 
total rows. 


For example, if num is set to 10, dbload aborts upon 
reaching the eleventh error. dbload aborts upon 
encountering the first bad row if num is set to O. 


-p 
instructs dbload to ask upon reaching the abort point 
whether to commit to the database the rows read 
since the last set of rows was committed, for data- 
bases with transactions. The default is to commit the 
lines to the database without asking for verification. 


-i num 
instructs dbload to ignore the first num number of 
rows in the system data file when executing your 
request. For example, this option is useful if the 
dbload program aborts after line 240 of the system 
file data, and you want to begin loading with line 241. 
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It is useful also if the system file contains header 
information preceding the data. 


The following example is an operating-system command line 
using all options (except -s) is: 


db loa d -d 
s tor e s -c 
com f i I e - I 
log f i I e 
-n 
50 -e 
5 -p -i 
20 


The example command line is explained as follows: 


-d stores 


-c comfile 


-I logfile 


-n 50 


-e 5 


-p 


-i 20 


stores is the name of the database. 


comfile is the name of the command file. 


logfile is the name of the error-logging file. 


indicates that dbload commits each set of 50 
good rows to the database. 


indicates that dbload allows 5 bad rows before 
aborting. 


indicates that dbload prompts for instructions 
about committing rows read, but not yet 
committed to the database, upon reaching the 
abort point. 


indicates that dbload ignores the first 20 lines 
of the data file. 


To abort the dbload program, press the interrupt key (DEL on 
UNIX systems, CTRL-C on DOS systems). Upon interrupt, rows 
read but not committed to the database are discarded. 


Suggestion: The speed with which the dbload utility loads data is 
greatly affected by the presence of indexes. Before running dbload. 
you may want to drop any indexes on the tables receiving the data. 
Then add new indexes when the program has finished. 


J-6 The dbload Utility 


The following examples shows the format of a command file. A 
discussion of each of the seven statements in this file follows 
the example. 


FILE datat I lel 
(Ildl 
1 - 
10 
: 
13 
: 
5 - 
22 
NULL = "st rl" 
, 
IId2 
10 - 
21 
: 
28 - 
32 
, 
IId3 
8 - 
10 
: 
33 
- 
50 
: 
29 - 
33 
NULL = "str2" 


IldN 
9 
: 
16 - 
19 
NULL = "string") 
; 


INSERT .INTO tabl 
(coil, 
col2, 
col9, ... 
, 
coiN) 
; 


INSERT 
INTO 
tab2 
VALUES 
(I I d 1, 
I I d3, 
"kev I n", 
. 
. 
. 
, 
I I dN) 
: 


INSERT 
INTO 
tab3 
: 
Ino 
column 
or 
values 
list 
provldedl 


FILE "datat I le.2" DELIMITER "I" Num 
; 
Ivariable 
length lieldsl 


INSERT 
INTO 
tabl 
VALUES 
(tal, 
102, 
"kev in", 
"234", ... 
, 
ION) 


INSERT 
INTO 
tab4 
: 


FILE dafat i le1 
(t Id1 
1 - 
10 
: 
13 
: 
5 
- 
22 
NULL = "strP' 
• 


datafile1 is the name of the operating system data file. fid1, 
fid2, fid3, through fidN are the field names you select to 
identify each fixed-length data field. 


In this example, fid1 consists of the characters in positions 1 
through 10, 13, and 5 through 22 of every row of datafilel. 
(All rows end with a NEWLINE character.) 
Character positions 
can be repeated in each field and across fields. Character 
positions 5 through 10 and 13 appear twice in fid1, and 
characters 10, 13, and 21 appear in fields fid1 and fid2. 


In fid1 the NULL value is defined as str1. dbload places a 
NULL value in the column wherever str1 is encountered. 


fid2 consists of the characters in positions 10 through 21 and 
28 through 32. 


fid3 consists of the characters in positions 8 through 10, 33 
through 50, and 29 through 33. The NULL value in this field 
is defined as str2. 
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The field-definition process continues until the last field is 
reached. Here, fidN contains characters in positions 9 and 16 
through 19. The NULL value is defined as string. 


Characters and character sequences are separated within each 
field definition by a colon. Field definitions are separated from 
one another by a comma. The end of the set of field 
definitions is indicated with a right parenthesis and a 
semicolon. All statements end with a semicolon. 


INSERT 
INTO 
tab1 
(coI1, 
col2, 
col9 •.... 
coiN) 


The preceding statement is a standard RDSQL INSERT 
statement. call, col2, and so on are the actual database column 
names. Since no value list is provided, dbload takes the value 
list from the preceding FILE statement. dbload inserts fid] 
data into call; fld2, into col2; and fid3, into col9 of table tab]. 
(In this instance, columns 4 through 8 are skipped.) This 
process continues until fldN data is inserted into coiN. 


INSERT 
INTO 
tab2 
VALUES 
(fld1, 
fld3, 
"kevin", ...• 
fldN) 
; 


Since no column list is provided, dbload checks the system 
catalogs for the column list for table tab2. The values loaded 
into each column are specifically stated, Here, fld] is loaded as 
column1; fld3, as column2; and the constant kevin, as column3. 
The process continues until fidN appears in the final column. 


INSERT 
INTO 
tab3 
; 
:no 
column 
or 
values 
list 
provided: 


Since no column or value list is provided, dbload checks the 
system catalogs for the column list for table tab3, and the value 
list is taken from the prior FILE statement (appearing at the 
start of the command file). 


In this example, the value fid] is placed in column1; fid2, in 
column2; fld3, in column3; and fidN in columnN. 


Note: 
This statement requires that the field list in the FILE 
statement have a one-to-one correspondence with the columns 
in the system catalogs. When this correspondence is not 
present, dbload does not load the rows. Instead, you receive 
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an error message on each row. dbload aborts the loading pro- 
cess when the total number of bad rows exceeds the user- 
specified limit (if indicated) or the default limit of 10 bad rows. 


A comment Ino column or values list provided: is enclosed in 
braces. 


FILE "data1 i le.2" DELIMITER "I" Num 
; 
lvar iable 
length 
1 ieldsl 


Columns in datafile.2 are of variable length. The DELIMITER 
clause in this statement tells dbload that the T' character 
separates each column. The same delimiter must be used 
throughout the file and must appear within quotation marks. 
Num is the number of columns that make up one row in the 
data file. Fields are automatically assigned the names f01, f02, 
f03, and so on. Any field that contains no characters is 
assigned a NULL value (CHAR fields are padded with blanks). 


Because the filename contains an extension (.2), the filename 
must be enclosed in quotes (ttdatafile.2tt ). 


INSERT 
INTO 
tab1 
VALUES 
(101, 
f02. 
"kevin", 
"234"•...• 
fON) 
; 


Since no column list is provided, dbload checks the system 
catalogs for this information. The values loaded into each 
column of tab1 are specifically stated. Here, f01 is loaded as 
column1; f02, as column2; the constant kevin, as column3; the 
value 234, as column4; and so on, until the value fON is placed 
in the last column. 


You must reference fields in a variable length data file with the 
letter "f" followed by a two digit number: f01, f02, flO, and so 
on. The format fid01 or f3 is incorrect. 


INSERT 
INTO tab4 
; 


Since no column or value list is provided, dbload checks the 
system catalogs for the column list for table tab4. The value 
list is taken from the previous FILE statement. The file list in 
the FILE statement must have a one-to-one correspondence 
with the columns in the system catalogs. In this instance, the 
value f01 is placed in column1; f02, in column2; f3, in column3; 
and so on, until the value fON is placed in columnN. 
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The complete operating-system command line syntax is 


dbload I -d dbname I -c cfile I -I lfile : ••. 
[-sl [an num] [-e num] rap] [-i num] 


-d dbname 


-c cfile 


-I lfile 


-8 


-n num 


-e num 


-p 


-i num 


is the name of the database that receives the new 
information. 


is the name of the dbload command file. 


is the name of the error-logging file. 


instructs dbload only to check the syntax of the 
cfile statement-no data is loaded into the 
database. 


gives the number of rows (num) read by dbload 
before committing the rows to the database 
(default = 100 rows). 


is the total number of bad rows (num) processed 
before dbload aborts (default = 10 rows; dbload 
aborts on bad row 11.) 


instructs dbload about what to do upon reaching 
the abort point. dbload asks about committing 
rows read, but not yet committed to the data- 
base, since the last commit was performed 
(default = commit). 


instructs dbload to ignore the first num number 
of rows in the data file. 


You must include at least one of the above options. If you do 
not include the first three options, dbload prompts for the 
information (database name, command filename, and error 
logging filename) it must have. 
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Appendix J 


Complex Outer Joins 
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Complex Outer Joins 


When more than two tables participate in an outer join, there 
are many ways to relate them. For three tables, there are five 
logically distinct joins, of which four involve.outer joins. These 
are listed as examples in this section using the notation used in 
SELECT statements and a graphic representation that can be 
generalized for any number of tables. The detailed rules for the 
graphic representations are at the end of this section and they 
appear as Figures J-I through J-6. Briefly, subservient tables 
are placed on a lower level than dominant tables. 


You would graphically represent the two-table outer join 
described in Chapter 1 as shown here: 


select 
a, 
b 
from tab1, 
outer 
tab2 
where 
a = b 


tab1 - 
0 
I 
tab2 


Leve I 
1 


Level 
2 


In the examples that- follow, the tilda symbol'" represents any 
Boolean relation between the columns of two tables. 


Example 
1 


from x. 
Y. 
z 
where ... 


x - 
y 
- 
z 
Leve I 
1 


This is the standard inner join and all three tables are treated 
on the same level. There are no restrictions on the WHERE 
clause. It need not exist. Before the WHERE clause is 
applied, a full Cartesian product is made among all three tables. 
(Note: A Cartesian product of two tables appends every row of 
the second table to every row of the first. A Cartesian product 
of three tables is the Cartesian product of the third with the 
Cartesian product of the first two, and so on.) 
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Example 
2 


from x. 
y. 
0 ute r 
z 
where 
(x 
or 
y) 
- 
z 


x -- y 
o 
I 
Leve I 
1 


z 
Level 
2 


This example illustrates the simplest extension of the outer join 
from two tables to three tables. x and yare joined at the same 
level and are shown connected together. z is the subservient 
table and is placed down one level. The WHERE clause must 
relate a Level 1 table with a Level 2 table. Other relationships 
are also permitted. Before the WHERE clause is applied, 
RDSQL takes the Cartesian product of x and y and then takes 
the outer join of the result with z. 


Example 
3 


from x. 
outer 
y. 
outer 
z 
where 
x 
- 
y 
and 
x 
- 
z 


x--0--0 


I 
I 
y 
z 


Leve I 
1 


Level 
2 


Although both y and z are at the same level, they are not con- 
nected. Here, a relationship is required between x and y and 
also between x and z. No relationship is permitted between y 
and z since they are not connected at the second level. The 
outer join is performed between x and y and then the outer 
join between the resulting table and z. 


Example 
4 


from x. 
0 ute r 
( y, 
z) 
wh ere 
x 
(y 
0 r 
z) 


x -- 0 


I 
y -- z 
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Level 
1 


Leve I 
2 


In Example 4, a relationship is required between x and either y 
or z, or both. In addition, there can be a relationship between 
y and z since they are connected at the second level. To 
perform this join, RDSQL starts at the top and works down. For 
each row of x, RDSQL attempts to find a row of y that satisfies 
the WHERE clause. If none is found, RDSQL substitutes NULL 
values for the columns of y and z. If a row of y satisfies the 
WHERE clause, RDSQL seeks a row of z that satisfies the 
WHERE clause. It substitutes NULL values for both y and z 
if no row in z is found. 


Example 5 


from x, 
0 ute r 
( y, 
0 ute r 
z) 
where x 
y and 
y 
z 
x- 0 
Level 
1 
Iy- 0 
Level 
2 
I 
z 
Level 
3 


Example 5 shows a three-level outer join. There must always 
be a relationship between adjacent levels. In this case, x must 
be related to y, and y must be related to z. RDSQL performs 
this join by picking a row from x and looking for a pair from y 
and z that satisfies (y, outer z). 


If each of the three tables consists of a single column with the 
values shown in the following table, then the previously 
described joins will result in the subsequent tables. In these 
examples, the tilda '" is taken to be equality between the 
columns. 
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x.a 


1 
2 
3 
5 


Figure J-l. Initial Tables 


Example 


y.b 


2 
3 
4 


z.e 


3 
4 
5 


select 
• 
from x, 
y, 
z 
where 
x.a = z.C 


a 


3 
3 
3 
5 
5 
5 


b 


2 
3 
4 
2 
3 
4 


e 


3 
3 
3 
5 
5 
5 


Figure J-2. Example 1 Results 


Example 
2 


select 
• 
from 
x·, 
y, 
0 ute r 
z 
where 
x.a = z.C 
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a 
b 
c 


1 
2 
1 
3 
1 
4 
2 
2 
2 
3 
2 
4 
3 
2 
3 
3 
3 
3 
3 
4 
3 
5 
2 
5 
5 
3 
5 
5 
4 
5 


Figure J-3. Example 2 Results 


Example 
3 


select 
• 
from 
x, 
0 ute r 
y, 
0 u' t e r 
z 
where x,a = y.b and x.a = z.C 


a 


1 
2 
3 
5 


b 


2 
3 


c 


3 
5 


FigureJ-4. Example 3 Results 
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Example 
4 


select 
• 


from x. 
0 ute r 
(y. 
z) 
where x.a = Z.c 


a 


1 
2 
:3 
:3 
:3 
5 
.5 
5 


b 


2 
3 
4 
2 
3 
4 


c 


3 
3 
3 
5 
5 
5 


Figure J-5. Example 4 Results 


Example 
5 


select 
• 


from x. 
0 ute r 
(y. 
0 ute r z) 
where x.a = y.b 
and 
y.b = Z.c 


a 
b 
c 


1 
2 
2 


:3 
5 


:3 
3 


Figure J-6. Example 5 Results 


.J-8 Complex Outer .Joins 


The following steps are useful when considering how RDSQL 
performs an outer join: 


1. Draw the graph corresponding to the FROM clause. 
Replace each keyword OUTER with the symbol 0 and put 
the table names to which the keyword applies in the next 
lower level. 


2. Ensure that a condition exists in the WHERE clause 
relating a table on each level through each 0 to a table in 
the next level below. 


3. Form a Cartesian product of all tables connected on the 
same level, applying those conditions of the WHERE clause 
that apply only to that level. 


4. Starting with the first level, take a row at a time from the 
resulting table and attempt to satisfy the WHERE clause 
with the resulting table of the next lower level, replacing the 
columns of the lower level table with NULL values if the 
WHERE clause cannot be satisfied. 


For example, the following FROM clause results in the 
accompanying graphic representation: 


from 
x, 
0 ute r 
(y, 
0 ute r 
(z, 
a, 
b», 
0 ute r 
c, 
d 


x - 
0 
0 -d 
Level 
1 
I 
I 
y - 
0 
C 
Level 
2 
I 
z - 
a - 
b 
Level 
3 


A Cartesian product is made between x and d (call it txd) and 
between z, a, and b (call it tzab), since these sets of tables are 
connected on the same level. y and c are both on Level 2, but 
they are not connected on that level. For each row of txd. 
RDSQL attempts to find a row of y that satisfies the WHERE 
clause. If it succeeds, it searches for a row of tzab that 
satisfies the WHERE clause. In both cases, NULL values are 
substituted if no satisfactory row is found. RDSQL then searches 
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for a row of c that satisfies the WHERE clause, substituting 
NULL values if unsuccessful. 
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Appendix K 


The dbschema Utility 
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The dbschema Utility 


The Database Administrator (DBA) can use the dbschema 
utility to quickly produce an RDSQL command file containing 
the CREATE TABLE, CREATE INDEX, and CREATE 
VIEW statements required to replicate an entire database or a 
selected table. In addition, dbschema can produce all 
CREATE SYNONYM and GRANT statements in effect for the 
database or a selected table or view. 


By default, dbschema produces all CREATE TABLE, 
CREATE VIEW, CREATE INDEX, CREATE SYNONYM, 
and GRANT statements in effect for the entire database. By 
including the appropriate command line option, you can limit 
the output to a selected table or view, or produce synonyms 
and permissions for a particular user. 


The syntax for the dbschema utility appears below: 


dbschema [-t tabname] [-s sname1[-p pname] -d database [filename1 


-t tabname 


-s sname 


identifies tabname as the table or view for 
which dbschema ol}tputs the CREATE 
TABLE and CREATE INDEX statements or 
the CREATE VIEW statement. If tabname is 
all, the RDSQL statements for all database 
tables and views are output. 


identifies sname as the user for which 
dbschema outputs the CREATE SYNONYM 
statements. If sname is all, the RDSQL state- 
ments for all users are output. If you.include 
the -t option, dbscherna produces the 
CREATE SYNONYM statements only for the 
indicated table-name. 
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-p pname 


-d database 


filename 


Notes 


identifies pname as the user for which 
dbschema outputs permissions. If pname is 
all, the RDSQL statements necessary to grant 
permissions to all users are output. If you 
include the -t option, dbschema produces the 
GRANT statements only for the indicated 
table-name. 


is the name of the database. 


is the name of the file receiving the RDSQL 
statements. If filename is not provided, 
dbschema writes to the terminal screen. 


1. The default command line appears below and produces the 
RDSQL statements necessary to replicate an entire database: 


dbschema -d database 


2. When you include the -t option, dbschema produces RDSQL 
statements only for the indicated table-name. dbschema 
uses the table-name to filter the output. If you request 
CREATE SYNONYM and GRANT statements, these are 
provided only for table-name. 


3. Most statements appear with comments. Depending upon 
the information requested, dbschema indicates the owner 
of the table, owner of the synonym, or grantor of a 
permission. 


4. All SERIAL fields included in CREATE TABLE statements 
output by dbschema have a starting value of one. 
regardless of their original starting value. 


5. The database must exist in your current directory or a 
directory cited in your DBPATH environment variable. 
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Examples 


The following statement outputs the RDSQL statements relating 
to the customer table in the stores database to the c 
all file. 


dbschema -t 
customer -s nancy -p bettyjo -d stores 
c al I 


The output consists of the following statements: 


• 
The CREATE TABLE and CREATE INDEX statements 
replicating the customer table 


• 
All CREATE SYNONYM statements executed by the user 
nancy on the customer table 


• 
All permissions granted to the user bett)jo on the customer 
table 
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The output from the dbschema statement follows: 


:enid 
is 
owner 
01 
table 
customer: 
create 
table 
customer 
( 
custnum serial 
not 
null, 
Iname 
char(15) 
I name 
c h a r ( 15) , 
company 
char(20). 
address1 
char(20), 
address2 char(20), 
city 
char(15), 
state char(2), 
zipcode 
char(5), 
phone 
cha r (18) 
) ; 


:enid 
is 
owner 
01 
index 
c_num_ix: 
create 
unique 
index 
c_num_ix 
on 
customer 
(custnum); 


:enid 
is 
owner 
01 
index 
zip_ix: 
create 
index 
zip_ix 
on 
customer 
(zipcode); 


rev 0 k e 
a I Ion 
c u s tome r 
from 
pub I i c ; 


:nan c y 
i sown e r 
0 f 
s y non ym 
c u s t : 
create 
synonym cust 
for 
customer; 


llel ix 
is 
the 
grantor; 
grant 
al I 
on 
customer 
to bettyjo; 


The next dbschema statement outputs the RDSQL statements 
relating to all tables in the database to the s_out file. 


db s c h ema -t 
a I I -s 
I eli x -p 
I eli x -d 
s tor e s sou t 


The output consists of the following statements: 


• 
The CREATE TABLE, CREATE VIEW, and CREATE 
INDEX statements that replicate all tables, views, and 
indexes in the stores database 


• 
All CREATE SYNONYM statements executed by the 
user felix 


• 
All permissions granted to the user felix 
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INFORMIX-ESQL/C 
Error Messages 


INFORMIX-ESQLlC Error Messages-2 INFORMIX-ESQLlC Error Messages 


This section contains the text of the INFORMIX-ESQLlC error 
messages. It also describes how the system responds to each 
error and suggests corrective actions. 


All INFORMIX-ESQL/C errors are returned by number in 
sqlca.sqlcode. These number from -200 to -1300. The C-ISAM 
errors are returned in sqlca.sqlerrd[l]. These are numbered 
from -100 to -199. You can use these numbers to locate the 
error description and a possible reGovery response in the follow- 
ing list: 


-100 
Description of Error: C-ISAM error: there is already 
a record with the same value in a unique key. 


System Action Taken: The statement was not 
processed. 


Corrective Action: Check that you did not attempt to 
add a duplicate value to a column with a unique index 
by way of iswrite, isrewrite, isrewcurr, or isaddindex. 


-101 
Description of Error: C-ISAM error: file is not open. 


System Action Taken: The statement was not 
processed. 


Corrective Action: Check that the C-ISAM file has 
been opened using the isopen call, or that you have not 
tried to write to a C-ISAM file opened for read only. 


-102 
Description of Error: C-ISAM error: illegal argument 
to C-ISAM function. 


System Action Taken: The statement was not 
processed. 
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Corrective Action: Check that one of the arguments 
to the C·ISAM call is not outside the range of acceptable 
values for that argument. 


-103 
Description of Error: C·ISAM error: illegal key 
descriptor (too many parts or too long). 


System Action Taken: The statement was not 
processed. 


Corrective Action: Check that one or more of the 
elements that make up the key description is not out- 
side the range of acceptable values for that element. 
(There is a maximum of 8 parts and 120 characters to 
each key descriptor.) 


-104 
Description of Error: C-ISAM error: too many files 
open. 


System Action Taken: The statement was not 
processed. 


.Corrective Action: The maximum number of files 
that can be open at one time would be exceeded if this 
request were processed. Reduce the number of open 
files by breaking your program up into two or more 
parts. On UNIX systems (and most DOS systems), the 
maximum number of open files per process is 20. If 
running under DOS, check that your CONFIG.SYS file 
contains the line 


FILES=20 


-105 
Description of Error: C-ISAM error: bad ISAM file 
format. 


System Action Taken: The statement was not 
processed. 
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Corrective Action: The format of the C-ISAM file has 
been corrupted. Run the bcheck utility on the file, and 
it will try to repair damaged indexes. If bcheck cannot 
repair the file, you must reload your data from a backup 
medium. 


-106 
Description of Error: C-ISAM error: non-exclusive 
access. 


System Action Taken: The statement was not 
processed. 


Corrective Action: You must first open the file with 
exclusive access when you want to add or delete an 
index. 


-107 
Description of Error: C-ISAM error: record is locked. 


System Action Taken: The statement was not 
processed. 


Corrective Action: The record or file requested by 
this call cannot be accessed because it has been locked 
by another user. Wait a moment and reenter your 
request. 


If you are certain that the table is not in use, you may 
need to empty the contents of the tablename.lok file. 
(This file contains information about which rows of the 
table are being used at anyone time. It is normally 
emptied when a user finishes accessing the table. On 
occasion, the file is not emptied and, as a result, no one 
is able to use the table.) You can copy the "file" 
Idev/null into this file to remove all locks on rows in 
the table. Contact your System Administrator about 
this action. 


Error Messages-5 


-108 
Description of Error: C-ISAM error: key already 
exists. 


System Action Taken: The statement was not 
processed. 


Corrective Action: You have attempted to add an 
index that previously has been defined. You must 
delete the existing index before defining another. 


-109 
Description of Error: C-ISAM error: the key is the 
primary key of the file. 


System Action Taken: The statement was not 
processed. 


Corrective Action: An attempt was made to delete 
the primary key column. The primary key cannot be 
deleted by the isdelindex call. 


-110 
Description of Error: C-ISAM error: end or beginning 
of the file. 


System Action Taken: The statement was not 
processed. 


Corrective Action: You have reached the beginning 
or end of the file. 


-111 
Description of Error: C-ISAM error: no record found. 


System Action Taken: The statement was not 
processed. 


Corrective Action: No record could be found that 
contained the requested value in the specified position. 
Edit your request and reenter; 


Error Messages-6 


-112 
Description of Error: C-ISAM error: there is no 
current record. 


System Action Taken: The statement was not 
processed. 


Corrective Action: An attempt to access a record in 
the current list has been made, but there is no current 
list. You must first perform a query and obtain a 
current list. 


-113 
Description of Error: C-ISAM error: the file is locked. 


System Action Taken: The statement was not 
processed. 


Corrective Action: The table you want to alter is 
currently in use by another user in exclusive mode. 
Wait until the table is no longer being used before 
entering your request. 


If you are certain that the table is not in use, run the 


, RDSQL UNLOCK TABLE command to unlock the 
table. Also, if your system contains tablename.lok files, 
you may need to empty the contents of the 
tablename.lok file. 
(This file contains information 
about which rows of the table are being used at anyone 
time. It is normally emptied when a user finishes 
accessing the table. On occasion, the file is not emptied 
and, as a result, no one is able to use the table.) You 
can copy the file /dev/null into this file to remove all 
locks on rows in the table. Be certain no processes are 
accessing the locked table before emptying the 
tablename.lok file. Contact your System Administrator 
about this action. 


Error Messages-7 


-114 
Description of Error: C-ISAM error: the filename is 
too long. 


System Action Taken: The statement was not 
processed. 


CorrectivE: Action: Reduce the filename length to 8 or 
fewer characters (if using DOS), or 10 or fewer charac- 
ters (if using UNIX). 


-116 
Description of Error: C-ISAM error: cannot allocate 
memory. 


System Action Taken: The statement was not 
processed. 


Corrective Action: Insufficient memory is available 
to run your request. 
(INFORMIX-ESQLlC has run out of 
addressable data space.) Reduce the complexity of your 
statement or form. 


-118 
Description of Error: Cannot read transaction log 
record. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Run the dblog utility to deter- 
mine which record contains the problem. 


-119 
Description of Error: Bad log record. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Run the dblog utility to deter- 
mine which record contains the problem. 


Error Messages-8 


-120 
Description of Error: Cannot open log file. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Make sure that the file exists, that 
you are using the correct pathname, and that you have 
the appropriate permissions to use the file. 


-121 
Description of Error: Cannot write log file record. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that you have the appropri- 
ate file permissions. 


-122 
Description of Error: BEGIN WORK encountered in 
a database without transactions. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Make sure that you have 
CREATEd or STARTed your database with transac- 
tions. 


-123 
Description of Error: No shared memory. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that the Database Adminis- 
trator has set up the shared memory partition. 


Error Messages-g 


-124 
Description of Error: No BEGIN WORK found. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You must execute BEGIN WORK 
before COMMIT WORK or ROLLBACK WORK. 


-125 
Description of Error: Cannot use NFS. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Do not attempt to access remote 
files on the network using NFS. 


-126 
Description of Error: Audit trail exists. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You cannot specify a new audit 
trail on a table without dropping the current one. 


-200 
Description of Error: Identifier is too long. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Identifiers must be nc. longer than 
18 characters. Select a new identifier of the appropri- 
ate length. 


Error Messages-IO 


., .... 


-201 
Description of Error: A syntax error has occurred. 


System Action Taken: The statement containing the 
syntax error was not processed. 


Corrective Action: Check that you have not 
misspelled an RDSQL statement, placed key words out of 
sequence, or included an I~FORMIX-ESQLlCreserved word 
in your query. 


-202 
Description of Error: An illegal character has been 
found in the statement. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Remove the illegal character 
(often a non-printable control character) and resubmit 
the statement. 
. 


-203 
Description of Error: An illegal integer has been 
found in the statement. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Integers must be whole numbers 
from -2,147,483,647 to 2,147,483,647. Check that you 
have not included a number with a fractional portion or 
a number outside of the range of acceptable whole 
numbers. Check also that you have not inadvertently 
entered a letter in place of a number (for example, 
125p3 instead of 12503). 


Error Messages-ll 


-"204 
Description of Error: An illegal floating-point 
number has been found in the statement. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that you have not inadver- 
tently entered a letter in place of a number (for exam- 
ple, 125b3 in place of 12503). 


-205 
Description of Error: Cannot use ROWID for views. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Restructure your statement so 
that the virtual column is not used to define the view. 


-206 
Description of Error: The specified table name is not 
in the database. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the spelling of the table 
name in your statement. Check the systables system 
catalog for a list of all database tables. 


-207 
Description of Error: Cannot update cursor declared 
on more than one table. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that you have not 
attempted to use a FOR UPDATE clause with cursors 
on multiple tables. Restructure your update statement, 
perhaps using multiple cursors. 


Error Messages-12 


-208 
Description of Error: Memory allocation failed 
during query processing. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Reduce the complexity of your 
query or program. 


-209 
Description of Error: Incompatible database format. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You are attempting to use 
INFORMIX-ESQL/C with a database built for an earlier 
version of INFORMIX-ESQL/C. Run dbupdate on your 
database. It prepares the database for your current ver- 
sion of INFORMIX-ESQL/C. 


-210 
Description of Error: Pathname too long. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: INFORMIX-ESQLlC accepts a path- 
name of up to 70 total characters. Reduce the length of 
the pathname. 


-211 
Description of Error: Cannot read system catalog 
catalog-name. 


System Action Taken: See below for a list of system 
actions. 


Corrective Action: Check the C-ISAM error for infor- 
mation about the source of the problem. Depending 
upon the content of the statement and the system cata- 
log cited in the error message, the following actions 
have occurred: 


Error Messages-13 


I 


For a CREATE TABLE statement: the systabauth 
catalog was not read, the table was created, but no 
authorizations are granted to PUBLIC. 


For a DROP TABLE statement: if the systables cata- 
log was not read, then no action was taken; if the 
sysviews catalog was not read, then the table was 
dropped but any views built on the table may not have 
been dropped. 


For a DROP VIEW statement: the sysviewscatalog 
was not read, and no action was taken. 


For a DROP INDEX statement: the sysindexes or 
systables catalog was not read, and the index was not 
dropped. 


For a DROP SYNONYM statement: the syssynonym 
catalog was not read, and the synonym was not 
dropped. 


For a DROP DATABASE statement: the systables 
catalog was not read, and the database was not 
dropped. 


For a START DATABASE statement: the systables 
catalog was not read, and the database was not started. 


For a DATABASE statement: the systables or 
sysusers catalog was not read, and the database was 
not selected. 


-212 
Description of Error: Cannot add index. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


Error Messages-14 


-213 
Description of Error: Statement interrupted by user. 


System Action Taken: The statement was not 
processed. 


Corrective Action: INFORMIX.ESQLlC has received an 
interrupt signal (probably due to the user pressing the 
DEL key). Resubmit your statement. 


-214 
Description of Error: Cannot remove file for table 
tablename. 


System Action Taken: If this is a DROP DATA- 
BASE statement, then some tables may have been 
dropped from the database. If this is a DROP TABLE 
statement, then some system entries for the table may 
have been dropped from the database. 


Corrective Action: INFORMIX-ESQLlC cannot remove 
one or more of the system catalogs that make up a 
table. Check the C-ISAM error for information about the 
source of the problem. Check with the System 
Administrator about remedial actions. 


-21.5 
Description of Error: Cannot open file for table 
tablename. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISA:\I error for 
information about the source of the problem. 


Error Messages-I5 


-216 
Description of Error: Cannot remove ISAM index on 
file. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


-217 
Description of Error: Column column-name not 
found in any table in the query. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Correct the spelling of the column 
name or check that column name exists in the database 
table. Check for the presence of required commas and 
quotes. 


-218 
Description of Error: Synonym name not found. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the spelling of the 
synonym. If needed, check the syssynonyms system 
catalog for a list of available synonyms. 


-219 
Description of Error: Wildcard matching used with a 
non-character data type. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Wildcards ( *, ?) and characters 
enclosed in brackets [ ] can be used only with CHAR 
data types. Check the data type of the column. 


Error Messages-16 


-220 
Description of Error: There is no FROM clause in 
the query. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You must include a FROM clause 
in the query. Check that you do not have an illegal 
character ($, #, &, or a CONTROL character) in the 
line prior to the FROM keyword. 


-221 
Description of Error: Cannot build temporary file for 
new table table-name. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: C-ISAM cannot access the Itmp 
directory or the disk may be out of space. Check the 
C-ISAM error for information about the source of the 
problem. 


-222 
Description of Error: Cannot write to temporary file 
for new table table-name. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: The disk may be out of space. 
Check the C-ISAM error for information about the source 
of the problem. 


-223 
Description of Error: Duplicate table name table- 
name in the FROM clause. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Remove the redundant table name 
from the statement or use an alias to rename one of the 
tables. 


Error Messages-I7 


-224 
Description of Error: Cannot open log file. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISA:\I error for 
information about the source of the problem. 


-225 
Description of Error: Cannot create file for system 
catalog catalog-name. 


System Action Taken: The CREATE DATABASE 
statement was not completed. Some system catalogs 
may ha\-e been created. 


Corrective Action: Check the C-ISA:\I error for 
information about the source of the problem. 


-226 
Description of Error: Cannot create index for system 
catalog catalog-name. 


System Action Taken: The CREATE DATABASE 
statement was not completed. Some system catalogs 
may have been created. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


-227 
Description of Error: Cannot use ORDER BY clause 
when selecting into temporary table. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Remove the ORDER BY clause 
from your statement. Place an index on the column 
you want to order by after creating the temporary table. 


Error Messages-I8 


-228 
Description of Error: Cannot have negatiw 
characters. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that you have not included 
a negative CHAR data type (for example, -a or -p) in 
your statement. 


-229 
Description of Error: Cannot open or create a tem- 
porary file. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISA:\f error for 
information about the source of the problem. 


-230 
Description of Error: Cannot read a temporary file. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISA:\f error for 
information about the source of the problem. 


-231 
Description of Error: Cannot perform an aggregate 
function with a DISTINCT on the expression. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Select the expression into a tem- 
porary table and then perform an aggregate distinct on 
the temporary table. 


Error Messages-19 


-232 
Description of Error: Attempt to update SERIAL 
column column-name. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: The values appearing in a 
SERIAL column are provided by INFOR!\HX-ESQUC and 
cannot be updated. 


-233 
Description of Error: Cannot read record that is 
locked by another user. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Another user has locked the 
record. Wait a moment and reenter your request. 


-234 
Description of Error: Cannot insert into virtual 
column column-name. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: The specified column is derived 
from an expression or an aggregate function. Redefine 
the view. 


-235 
Description of Error: Character column size too big. 
The maximum size is 32,767. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Redefine the size of the column. 


Error Messages-20 


-236 
Description of Error: Number of columns in 
INSERT does not match number of VALUES. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that the number of 
columns in the table or in the column list matches the 
number of values in the VALUES clause or the 
SELECT clause. 


-237 
Description of Error: Cannot begin work. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error number 
for information about the source of the problem. Con- 
tact your System Administrator or Database Adminis- 
trator if you need assistance interpreting the C-ISAM 
error number. 


-238 
Description of Error: Cannot COMMIT WORK. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Your log file may be corrupted. 
Check the C-ISAM error number for information about 
the source of the problem. Contact your System 
Administrator or Database Administrator if you need 
assistance interpreting the C-ISAM error number. 


Error Messages-21 


-239 
Description of Error: Cannot insert new row- 
duplicate value in a UNIQUE INDEX column. 


System Action Taken: The statement containing the 
error was. not processed. 


Corrective Action: The row contains a value that 
already exists in the column (indexed as unique) of an 
existing row. Enter a new value for the column or 
remove the unique index on the column. 


-240 
Description of Error: Cannot delete a row. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C·ISAM error for 
information about the source of the problem. 


-241 
Description of Error: Cannot ROLLBACK WORK. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C·ISAM error number 
for information about the source of the problem. Con- 
tact your System Administrator or Database Adminis- 
trator if you need assistance interpreting the C·ISAM 
error number. 


-242 
Description of Error: Cannot open database table 
table-name. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C·ISAM error for 
information about the source of the problem. 


INFORMIX-ESQLlC Error Messages-22 


-243 
Description of Error: Cannot position within a table 
table-name. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C·ISAM error for 
information about the source of the problem. 


-244 
Description of Error: Cannot do a physical-order 
read to fetch next row. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


-245 
Description of Error: Cannot position within a file 
by way of an index. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


-246 
Description of Error: Cannot do an indexed read to 
get the next row. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


INFORMIX-ESQLlC Error Messages-23 


-247 
Description of Error: ROLLFORWARD database 
failed. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C·ISAM error for infor- 
mation about the source of the problem. Contact your 
System Administrator or Database Administrator if you 
need assistance interpreting the meaning of the C·ISAM 
error. 


-248 
Description of Error: Value of the host variable in 
the WHERE clause is NULL. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Use IS [NOT] NULL for NULL 
operation or initialize the host variable. 


-249 
Description of Error: Virtual column has no explicit 
name. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: When selecting into a temporary 
table or creating a view, each temporary or view column 
based on an expression must be given a unique name. 
Check that distinct names are provided. 


-250 
Description of Error: Cannot read record from file 
for update. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: The record may be locked by 
another user. Check the C-ISAM error for information 
about the source of the problem. 


INFORMIX-ESQLlC Error Messages-24 


-251 
Description of Error: Column number number too 
big. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: The number of the column noted 
in your ORDER BY or GROUP BY statement exceeds 
the total number of columns in the SELECT statement. 


-252 
Description of Error: Cannot get system information 
for table. 


System Action Taken: Some statistics may be 
updated. 


Corrective Action: Check the C-ISAM error for 
information a.bout the source of the problem. 


-253 
Description of Error: Identifier too long-maximum 
length is 18. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the spelling or length of the 
table name. 


-254 
Description of Error: Too many or too few host 
variables given. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that the number of host 
variables in the fetch is equal to the number used to 
define the cursor. 


INFORMIX-ESQLlC Error Messages-25 


-255 
Description of Error: Statement not in a 
transaction. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: The statement must be executed 
within a transaction. Start a transaction, then perform 
the statement. 


-256 
Description of Error: Transaction not available. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: INFORMIX-ESQLlC cannot perform a 
transaction operation (BEGIN WORK, ROLLBACK 
WORK, COMMIT WORK) on the database because a 
transaction log was never created for the database. Ask 
your Database Administrator to create a transaction log 
for the database. 


-257 
Description of Error: System limit on cursors 
exceeded; maximum is num. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Reduce the number of cursors 
used in the program. 


-258 
Description of Error: System error-invalid state- 
ment ID received by the sqlexec process. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Call the Technical Support 
Department. 


INFORMIX-ESQLlC Error Messages-26 


-259 
Description of Error: Cursor not open. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Open a cursor, then attempt the 
fetch. 


-260 
Description of Error: Cannot execute a SELECT 
statement that is PREPARED-must use cursor. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Use a cursor for the SELECT 
statement. 


-261 
Description of Error: Cannot create a file for table 
table. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


-262 
Description of Error: There is no current cursor. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You cannot perform an UPDATE 
or DELETE action when no current row exists. 
Perform a fetch, then attempt this action. 


; 


Error Messages-27 


-263 
Description of Error: Cannot lock row for UPDATE. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error for infor- 
mation about the source of the problem. 


-264 
Description of Error: Cannot write to a temporary 
file. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


-265 
Description of Error: Load or insert cursors was not 
run within a transaction. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You must start a transaction with 
a BEGIN WORK before using insert cursors. 


-266 
Description of Error: There is no current row for 
UPDATE/DELETE cursor. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You cannot perform an UPDATE 
or DELETE action when no current row exists. 
Perform a fetch, then attempt this action. 


Error Messages-28 


-267 
Description of Error: The cursor has been previously 
released and is unavailable. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Make sure that the cursor is open 
before you make reference to it. 


-268 
Description of Error: Cannot use SELECT 
DISTINCT with UNION ALL. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Rewrite your statement. 


-269 
Description of Error: Cannot add a column column- 
name that does not accept nulls. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Rewrite your statement. 


-270 
Description of Error: Cannot position within a tem- 
porary file. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


Error Messages-29 


-271 
Description of Error: Cannot insert new row into the 
table. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


-272 
Description of Error: No SELECT permission. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Request permission to SELECT 
from the owner of the table. 


.-273 
Description of Error: No UPDATE permission. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Request permission to UPDATE 
from the owner of the table. 


-274 
Description of Error: No DELETE permission. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Request permission to DELETE 
from the owner of the table. 


Error Messages-3D 


-275 
Description of Error: No INSERT permission. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Request permission to INSERT 
from the owner of the table. 


-276 
Description of Error: Cursor not found. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You have called for a cursor that 
has not been declared in the current session. 
(The 
current session runs from the issuance of a DATA- 
BASE statement to a CLOSE .DATABASE statement, 
or the issuance of the next DATABASE statement.) 
Declare your cursor within the current (database) 
session. 


-277 
Description of Error: UPDATE table table-name is 
not the same as the cursor table. 


System Action Taken: The statement containing the 
error v:;as not processed. 


Corrective Action: Either declare a cursor on the 
table used in the CPDATE statement. or update the 
table used in the cursor. Check the spelling of the table 
name and cursor name. 


-278 
Description of Error: Too many ORDER B\' 
columns: maximum is eight. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Reduce the number of columns 
included in the ORDER BY clause to eight or fewer. 


Error Messages-31 


-279 
Description of Error: Cannot GRANT or REVOKE 
database privileges for table or view. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Database privileges (Connect. 
Resource, and DBA) cannot be granted on individual 
tables. Consult the section "User Status and 
Privileges" in Chapter 1 for appropriate RDSQL table 
privilege statements. 


-280 
Description of Error: Total size of ORDER BY 
columns exceeds 120 bytes. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Reduce the number of columns 
included in the ORDER BY clause so that the total 
number of characters is less than or equal to 120 
(perhaps delete a CHAR column of 30 or more 
characters). 


-281 
Description of Error: Cannot add index to a 
temporary table. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


-282 
Description of Error: Found a quote for which there 
is no matching quote. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that all quoted strings are 
properly terminated with a quote. 


Error Messages-32 


-283 
Description of Error: Found a non-terminated 
comment ("I" with no matching "n. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that all comments are 
properly enclosed in braces. (Comments cannot be 
nested.) 


-284 
Description of Error: A subquery has returned not 
exactly one value. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check data for the subquery. 
Restructure the subquery by adding more components 
in the WHERE clause so that only onevah.ie is 
returned. 


-285 
Description of Error: Invalid cursor received by 
sqlexec. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Issue a PREPARE statement 
within the current session, then reenter your original 
statement. 


-286 
Description of Error: Expression cannot include 
ANY or ALL. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: ANY and ALL can only be used 
in association with a subquery. 


Error Messages-33 


-287 
Description of Error: Cannot add SERIAL column 
column-name to the table. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: A SERIAL column does not 
accept NULL values. Add the column to the table as 
type INTEGER, UPDATE it so that there are no 
NULLS, and then MODIFY it to type SERIAL. 


-288 
Description of Error: Table tablename not locked by 
current user. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You attempted to unlock a table 
that you did not lock. 


-289 
Description of Error: Cannot lock table tablename in 
share mode. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: The table is already locked in 
exclusive mode. Wait until the table is unlocked before 
reexecuting your request. 


-290 
Description of Error: Cursor not declared with FOR 
UPDATE clause. 


System Action Taken: The statement containing the 
errOr was not processed. 


Corrective Action: You have attempted to delete or 
update WHERE CURRENT OF without declaring the 
cursor for update. DECLARE your cursor FOR 
UPDATE. 


Error Messages-34 


-291 
Description of Error: Table table-name is already 
locked. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You must unlock the table before 
executing your request. 


-292 
Description of Error: An implied INSERT column 
column-name does not accept NULLs. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: RDSQL does not allow you to insert 
a NULL value in a column that does not allow NULLS. 
Check to see if a non-NULL column is included in the 
column list in the INSERT statement. 


-293 
Description of Error: IS [NOT] NULL predicate 
used with other than simple columns. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Restructure your query. 


-294 
Description of Error: The column column-name not 
in the GROUP BY list. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: All non-aggregate columns in the 
SELECT list must be included in the GROUP BY list. 
Restructure your statement to include all columns that 
are not aggregate functions. 


Error Messages-35 


-295 
Description of Error: The GROUP BY column 
number number is too large. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: The number of the column noted 
in your ORDER BY or GROUP BY statement exceeds 
the total number of columns in the SELECT statement. 


-297 
Description of Error: The SELECT list contains a 
subquery. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Remove the subquery from the 
SELECT list in the statement. 


-298 
Description of Error: COUNT(DISTINCT ...) used 
with other than a simple column. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You cannot include expressions 
with the COUNT(DISTINCT ...) function. Restructure 
the query. 


-299 
Description of Error: Query contains more than one 
DISTINCT. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Restructure your query to include 
only one DISTINCT. 


Error Messages-36 


-300 
Description of Error: There are too many GROUP 
BY columns (maximum is eight). 


System Action Taken: The request was not 
completed. 


Corrective Action: Reduce the number of columns in 
the statement to eight or fewer. 


-301 
Description of Error: The total size of the GROUP 
BY columns exceeds 120 characters. 


System Action Taken: The request was not 
completed. 


Corrective Action: The total number of characters in 
all columns listed in the GROUP BY list exceeds 120 
characters. Reduce the column list (perhaps exclude 
any columns with character data types greater than 30 
characters). 


-302 
Description of Error: No GRANT option. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You do not have permission tu 
grant access privileges to the table. Only the table 
owner or a user with GRANT permission can do this. 


-303 
Description of Error: Expression mixes columns 
with aggregates. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Restructure your query so that 
columns and aggregates are not included in the same 
expression. 


Error Messages-37 


-304 
Description of Error: Found HAVING clause with 
expressions other than aggregates. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: The HAVING clause can only 
take on aggregates. Restructure your query. 


-305 
Description of Error: Subscripted column column- 
name is not of type CHAR. 


System Action Taken: The request was not 
completed. 


Corrective Action: Remove the subscript delimiter 
from the non-character column name in the request. 


-306 
Description of Error: Subscript out of range. 


System Action Taken: The request was not 
completed. 


Corrective Action: The range of the subscript delim- 
iter exceeds the range of the column data type. Check 
the size of the data type and reduce the subscript range. 


-307 
Description of Error: Illegal subscript definition. 


System Action Taken: The statement did not run. 


Corrective Action: Check that you have not reversed 
the order of the subscript delimiters ([3,8] is a valid 
subscript; [8,3] is invalid) or included a negative 
number as a subscript delimiter. 
. 


Error Messages-38 


-308 
Description of Error: Column type not the same for 
each UNION statement. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the select-list of each 
SELECT statement to make sure that corresponding 
items have identical data types. 


-309 
Description of Error: ORDER BY column column- 
name not in SELECT list. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that columns included in 
the ORDER BY clause appear in the SELECT list. 


-310 
Description of Error: Table table-name already 
exists in database. 


System Action Taken: The request was not 
completed. 


Corrective Action: Select an alternate name for the 
table. 


-311 
Description of Error: Cannot open system catalog 
catalog-name. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


Error Messages-39 


-312 
Description of Error: Cannot update system catalog 
catalog"name. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISA!\t error for 
information about the source of the problem. 


-313 
Description of Error: Not owner of table table-name. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Only the owner of the table (or 
the Database Administrator) can remove the table. 


-314 
Description of Error: Table table-name currently in 
use. 


System Action Taken: The request was not 
completed. 


Corrective Action: The table you want to drop is 
currently being used by another user. Wait until the 
table is no longer in use before executing your request. 


-315 
Description of Error: No CREATE INDEX 
permission. 


System Action Taken: The request was not 
completed. 


Corrective Action: Permission not granted for you to 
create an index on the table. 


Error Messages-40 


-316 
Description of Error: Index index-name already 
exists in database. 


System Action Taken: The request was not 
completed. 


Corrective Action: An index currently exists for the 
table. You must drop the existing index before creating 
a new one. 


-31, 
Description of Error: The same number of selected 
columns does not appear in each UNION statement. 


System Action Taken: The request was not 
completed. 


Corrective Action: Check the number of columns 
selected in each SELECT statement. 


-318 
Description of Error: File with the same name as 
specified log file already exists. 


System Action Taken: The request was not 
completed. 


Corrective Action: Select a different name for the log 
file. 


-319 
Description of Error: Index does not exist in 
database file. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the spelling of the index 
name or check the sysindexes system catalog for the 
correct index name. 


Error Messages-41 


-320 
Description of Error: Not owner of index 
index-name. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Only the owner of the index (or 
the Database Administrator) can remove the index. 


-321 
Description of Error: Cannot group by aggregate 
column column-name. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the column number used in 
the GROUP BY clause. 


-322 
Description of Error: Cannot alter view L~iell·-name. 


System Action Taken: The request was not 
completed. 


Corrective Action: Views cannot be altered. You 
must drop and then recreate the view. 


-323 
Description of Error: Cannot grant permission on 
temporary table. 


System Action Taken: The request was Dot 
completed. 


Corrective Action: Permissions can only be granted 
on permanent tables. 


Error Messages-42 


( 


-324 
Description of Error: Ambiguous column 
column-name. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: A column name exists in more 
than one table cited in your query. Prepend each 
column name with the appropriate table name. 


-325 
Description of Error: Full pathname not specified 
for the log file. 


System Action Taken: The request was not 
completed. 


Corrective Action: Provide the full pathname for the 
log file. 


-326 
Description of Error: Expecting CHAR type host 
variable. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: The cursor is on a CHAR ~olumn 
and your program is attempting to pass it a non-CHAR 
data type. Restructure your statement. 


-327 
Description of Error: Cannot unlock table tablename 
within a transaction. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Do not issue UNLOCK TABLE 
within a transaction. 


Error Messages-43 


-328 
Description of Error: Column column-name already 
exists in table. 


System Action Taken: The request was not 
completed. 


Corrective Action: Select a new column name for the 
column. 


-329 
Description of Error: Database not found or no 
system permission. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the spelling of the database 
name. Check that the database name exists in your 
current directory or a directory included in your 
DBPATH environment variable. Check the C-ISAM 
error for information about the source of the problem. 


-330 
Description of Error: Cannot create database. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that you have not entered 
the name of an existing database. Select an alternate 
name for the database. Check the C-ISAM error for 
information about the source of the problem. 


-331 
Description of Error: Cannot drop database 
directory. 


System Action Taken: All database files in the data- 
base directory are deleted, but the directory remains. 


Corrective Action: Remove any non-database files 
present in the database directory, then remove the 
directory. Check the C·ISAM error for information about 
the source of the problem. 


Error Messages-44 


~332 
Description of Error: Cannot access audit trail name 
information. 


System Action Taken: The request was not 
completed. 


Corrective Action: Reexecute your request. If the 
error occurs again, the audit trail file is corrupt. You 
may need to drop and restart the audit trail. 


-333 
Description of Error: The audit trail file already 
exists with a different name. 


System Action Taken: The request was not 
completed. 


Corrective Action: You must drop the existing audit 
trail file (issue a DROP AUDIT FOR statement) before 
creating a new audit trail. 


~334 
Description of Error: Cannot create audit trail. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You must indicate the full path- 
name of the file receiving the audit trail. Check that 
you have permission to write to a file in the selected 
directory. Contact your System Administrator if you 
need help with this action. 


~335 
Description of Error: There is no audit trail for the 
specified table. 


System Action Taken: The request was not 
completed. 


Corrective Action: INFORMIX-ESQLlC is unable to 
recover the table as no audit trail was created. 


Error Messages-45 


r 


-336 
Description of Error: Attempt to create or drop 
audit on temporary table table-name. 


System Action Taken: The request was not 
completed. 


Corrective Action: You cannot place an audit trail on 
a temporary table. 


-337 
Description of Error: Attempt to create view on 
temporary table table-name. 


System Action Taken: The request was not 
completed. 


Corrective Action: You cannot create a view on a 
temporary table. 


-338 
Description of Error: Cannot drop audit trail. 


System Action Taken: The audit trail was not 
dropped (possible operating system error.) 


Corrective Action: Reexecute your request. If the 
problem reoccurs, check the C-ISAM error message for 
information about the source of the problem. Contact 
your System Administrator if you require assistance 
with this action. 


-339 
Description of Error: Full pathname not specified 
for the audit trail file. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Edit your statement to include the 
full pathname of the audit trail file. 


Error Messages-46 


-340 
Description of Error: Cannot open audit trail file. 


System Action Taken: The request was not com- 
pleted. 


Corrective Action: Check that you have operating 
system read permission to the file. Contact your Sys- 
tem Administrator if you need help with this action. 


-341 
Description of Error: Cannot read a row from audit 
trail file. 


System Action Taken: The request was not com- 
pleted. 


Corrective Action: Reexecute your request. If the 
error occurs again, the audit trail file is corrupt. You 
may need to drop and restart the audit trail. 


-343 
Description of Error: Row from audit trail was 
added to a different position than expected. 


System Action Taken: The request was not 
completed. 


Corrective Action: Reexecute your request. If the 
erf0r occurs again, the audit trail file is corrupt. You 
may need to drop and restart the audit trail. 


-344 
Description of Error: Cannot delete row-row in 
table does not match row in audit trail. 


System Action Taken: The request was not 
completed. 


Corrective Action: Reexecute your request. If the 
error occurs again, the audit trail file is corrupt. You 
may need to drop and restart the audit trail. 


Error Messages-47 


...,345 
Description of Error: Cannot update row-row in 
table does not match row in audit trail. 


System Action Taken: The request was not 
completed. 


Corrective Action: Reexecute your request. If the 
error occurs again, the audit trail file is corrupt. You 
may need to drop and restart the audit trail. 


-346 
Description of Error: Cannot update a row in the 
table. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


-347 
Description of Error: Cannot open table for 
exclusive access. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


-348 
Description of Error: Cannot read a row from the 
table. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C·ISAM error for 
inf<?rmation about the source of the problem. 


Error Messages-48 


-:349 
Description of Error: Database not selected yet. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Select a database before executing 
a statement that refers to a database. 


-350 
Description of Error: Index already exists on 
column. 


System Action Taken: The request was not 
completed. 


Corrective Action: Adding an index on the column is 
not necessary; the column is already indexed. 


-351 
Description of Error: Database contains tables 
owned by other users. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You can only drop a database if 
you own all tables in the database or have DBA status. 
Contact your Database Administrator if you need help 
with this action. 


-3.52 
Description of Error: Column not found. 


System Action Taken: The request was not 
completed. 


Corrective Action: Check the spelling of the column 
name. 


Error Messages-49 


-353 
Description of Error: No table or view specified' 
when granting or revoking table pri\'ileges. 


System Action Taken: The request was not 
completed. 


Corrective Action: You must include the name of the 
table or vie\}, on which a privilege is granted or revoked 
in your RDSQL statement. 


-354 
Description of Error: Incorrect database or cursor 
name format. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: A database name must be no 
longer than ten characters on UNIX systems or eight 
characters on DOS systems. A cursor name must be no 
longer than 18 characters on UNIX and DOS systems. 
A database or cursor name must begin with a letter, 
and contain letters, numbers, or underscores. Check 
that you have not included an illegal character in the 
name. 


-355 
Description of Error: Cannot rename file for table. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


Error Messages-50 


-356 
Description of Error: Table tablename specified in 
both main query and subquery. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: The statement is ambiguous 
because a column cannot be identified uniquely. Use an 
alias to rename the appropriate table. 


-357 
Description of Error: Dependent table for view 
viewname has been altered. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: A table upon which the view is 
constructed has been modified (for example, a column 
has been dropped, a data type has been modified, or a 
column has been added to the middle of the table). 
Drop the view and create a new view. 


-358 
Description of Error: Database not closed before 
CREATE, START, or ROLLFORWARD database. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Execute a CLOSE DATABASE 
statement, then attempt the action. 


-359 
Description of Error: Cannot drop current database. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Execute a CLOSE DATABASE 
statement before executing a DROP DATABASE 
statement. 


Error Messages-51 


-360 
Description of Error: Cannot modify table or dew 
used in subquery. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: If allowed, your statement could 
reduce to a looping program. Edit your statement. 


-361 
Description of Error: Column size too large. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Reduce the size of the column. 
You cannot have a CHAR column larger than 32,767 
characters. 


-362 
Description of Error: There is more than one 
column of SERIAL type. 


System Action Taken: The request was not 
completed. 


Corrective Action: You cannot have more than one 
column of SERIAL type in a table. Select an alternate 
data type for the column. 


-363 
Description of Error: Cursor not on SELECT 
statement. 


System Action Taken: The request was not 
completed. 


Corrective Action: Use EXECUTE to execute 
prepared objects on non-SELECT statements. 


Error Messages-52 


\ 


-364 
Description of Error: Column column-namE' not 
declared FOR UPDATE OF. 


System Action Taken: The request was not 
completed. 


Corrective Action: Include the column in the FOR 
UPDATE OF list. 


-365 
Description of Error: Cursor not on simple SELECT 
for FOR UPDATE. 


System Action Taken: The request was not 
completed. 


Corrective Action: Check that the cursor does not 
include more than one table or involve aggregates. 


-366 
Description of Error: The scale exceeds the max- 
imum precision specified. 


System Action Taken: The request was not 
completed. 


Corrective Action: The problem is located in a DEC- 
IMAL or MONEY column: the scale (number of digits 
to the right of the decimal point) exceeds the precision 
(total number of digits). 


DECIMAL(m,n) where n>m 
MONEY(m.n) 
where n>m 
MONEY(m) 
where m<2 


Error Messages-53 


-367 
Description of Error: Attempt to compute sums or 
averages for character columns. 


System Action Taken: The request was not 
completed. 


Corrective Action: Check that you have not included 
a column of character data type in the aggregate 
function statement. 


-368 
Description of Error: Incompatible database server 
module. 


System Action Taken: The request was not 
completed. 


Corrective Action: Check that the correct version of 
sqlexec is installed. Contact your Database Adminis- 
trator if you need help with this action. 


-369 
Description of Error: Invalid serial number. Consult 
your installation instructions. 


System Action Taken: The request was not 
completed. 


Corrective Action: Check that the correct version of 
sqlexec is installed. Contact your Database Adminis- 
trator if you need help with this action. 


-370 
Description of Error: Cannot drop last column. 


System Action Taken: The request was not 
completed. 


CorJ:"ective Action: Only one column remains in the 
table. Use the DROP TABLE statement to remove the 
table. 


Error Messages-54 


-371 
Description of Error: The column contains duplicate 
data. 


System Action Taken: The request was not 
completed. 


Corrective Action: You cannot create a unique index 
on a column containing duplicate data. 


-372 
Description of Error: Attempt to alter table with 
audit trail on. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You must drop the audit trail 
before making any changes to the table. After making 
the changes, you may want to reestablish an audit trail. 


-373 
Description of Error: DBPATH too long. 


System Action Taken: The request was not 
completed. 


Corrective Action: Reduce the length of your 
DBPATH environment variable. 


-374 
Description of Error: Attempt to use other than a 
column number in an ORDER BY clause with UNION. 


System Action Taken: The request was not 
completed. 


Corrective Action: Restructure the query using 
ordinal numbers for the ORDER BY columns. 


Error Messages-55 


-375 
Description of Error: Cannot create log file for 
transaction. 


System Action Taken: The request was not 
completed. 


Corrective Action: Check the C-ISAM error for 
information about the source of the problem. 


-376 
Description of Error: Log file already exists. 


System Action Taken: The request was not 
completed. 


Corrective Action: Select an alternate name for the 
log file. 


-377 
Description of Error: Attempt to close database 
before terminating a transaction. 


System Action Taken: The request was not 
completed. 


Corrective Action: Issue a COMMIT \VORK or 
ROLLBACK statement before closing the database. 


-378 
Description of Error: Record currently locked by 
another user. 


System Action Taken: The request was not 
completed. 


Corrective Action: Wait until the record is unlocked 
before submitting the statement. Check the C-ISAM 
error for information about the source of the problem. 


Error Messages-56 


-;)'79 
Description of Error: Cannot re\'oke prl\'llege on 
columns. 


System Action Taken: The request was not 
completed. 


Corrective Action: Revoke UPDATE or SELECT 
prl\'ilege on the table, then grant the revoked privileges. 


-380 
Description of Error: Cannot erase log file. 


System Action Taken: The request was not 
completed. 


Corrective Action: Check the C-15A1\I error for 
information about the source of the problem. 


-381 
Description of Error: Attempt to grant privilege to 
someone who has granted you the same privilege. 


System Action Taken: The request was not 
completed. 


Corrective Action: You must remove the name of the 
individual who granted you permission to use the table 
from your user list. 


~382 
Description of Error: Same number of columns not 
specified for view and select clause. 


System Action Taken: The request was not 
completed. 


Corrective Action: Check the number of columns in 
the view definition and in the selected columns. 
Specify the same number for each. 


Error Messages-57 


-388 
Description of Error: View column for aggregate or 
expression not explicitly named. 


System Action Taken: The request was not 
completed. 


Corrective Action: Provide a name for all virtual 
columns. 


-384 
Description of Error: Cannot modify non-simple 
view. 


System Action Taken: The request was not 
completed. 


Corrective Action: Only modify views built on a sin- 
gle table. 


-385 
Description of Error: Data value out of range. 


System Action Taken: The request was not 
completed. 


Corrective Action: Check the view definition for valid 
data ranges. 


-386 
Description of Error: Column contains null values. 


System Action Taken: The request was not 
completed. 


Corrective Action: The table contains NULL values 
in a column being altered to disallow NULLS. Remove 
NULL values from the column. 


Error Messages-58 


-387 
Description of Error: No connect permission. 


System Action Taken: The request was not 
completed. 


Corrective Action: Contact the Database Administra- 
tor and request connect permission. 


-388 
Description of Error: No resource permission. 


System Action Taken: The request was not 
completed. 


Corrective Action: Contact the Database Administra- 
tor and request resource permission. 


-389 
Description of Error: No DBA permission. 


System Action Taken: The request was not 
completed. 


Corrective Action: Contact the Database Administra- 
tor and request DBA permission. 


-390 
Description of Error: Synonym already used as table 
name or synonym. 


System Action Taken: The request was not 
completed. 


Corrective Action: Select a different synonym. 
Check the syssynonym system catalog for a list of 
existing synonyms. 


Error Messages-59 


-391 
Description of Error: Cannot insert a NULL into 
column column-name. 


System Action Taken: The request was not 
completed. 


Corrective Action: Check to see if a column that does 
not allow NULL values has been inserted in the column 
list. 


-392 
Description of Error: System error-unexpected null 
pointer encountered. 


System Action Taken: The request was not 
completed. 


Corrective Action: Contact the Technical Support 
Department. 


-393 
Description of Error: A condition in the where 
clause results in a two-sided outer join. 


System Action Taken: The request was not 
completed. 


Corrective Action: A two-sided outer join is not 
allowed. Restructure your query. 


-394 
Description of Error: View view-name not found. 


System Action Taken: The request was not 
completed. 


Corrective Action: Check the spelling of the view 
name. Check the sysviews system catalog for a list of 


exist~ng views. 


Error Messages-60 


-395 
Description of Error: The WHERE clause contains 
an outer Cartesian product. 


System Action Taken: The request was not 
completed. 


Corrective Action: Check the syntax of the 
statement. 


-396 
Description of Error: Illegal join between a nested 
outer table and a preserved table. 


System Action Taken: The request was not 
completed. 


Corrective Action: Check the syntax of the 
statement. 


-397 
Description of Error: System catalog corrupted. 


System Action Taken: The request was not 
completed. 


Corrective Action: Contact the Database 
Administrator for help with this error. 


-398 
Description of Error: Cursor manipulation does not 
fall within a transaction. 


System Action Taken: The request was not 
completed. 


Corrective Action: Perform a BEGIN WORK 
statement before any cursor manipulations. 


Error Messages-61 


-399 
Description of Error: Cannot access log file. 


System Action Taken: The request was not 
completed. 


Corrective Action: You cannot edit the log file. 


-400 
Description of Error: Fetch attempted on unopen 
cursor. 


System Action Taken: The statement did not run. 


Corrective Action: Check that the cursor was prop- 
erly opened using an OPEN CURSOR statement. 


-401 
Description of Error: Fetch attempted on NULL 
cursor. 


System Action Taken: The statement did not run. 


Corrective Action: Check that the cursor was 
properly opened using an OPEN CURSOR statement. 


-402 
Description of Error: Address of a host variable is 
NULL. 


System Action Taken: The statement did not run. 


Corrective Action: Check the addresses of each host 
variable (one or more have a NULL value). 


-403 
Description of Error: The size of a received row 
disagrees with the expected size. 


System Action Taken: The statement did not run. 


Corrective Action: Check that you are using the 
proper library in the program. 
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-404 
Description of Error: A NULL control block has 
been passed as an argument. 


System Action Taken: The statement did not run. 


Corrective Action: Check that you are using the 
proper library in the program. 


-405 
Description of Error: The address of a host variable 
is not properly aligned. 


System Action Taken: The statement did not run. 


Corrective Action: Check that each host variable is 
aligned with the proper address boundary for variables 
of that type. 


-406 
Description of Error: Memory allocation failed. 


System Action Taken: The statement did not run. 


Corrective Action: Exit to the operating system com- 
mand line, and resubmit your program. 


-407 
Description of Error: Error number zero received 
from the sqlexec process. 


System Action Taken: The statement did not run. 


Corrective Action: Exit to the operating system com- 
mand line, and resubmit your program. 


-408 
Description of Error: Invalid message type received 
from the sqlexec process. 


System Action Taken: The statement did not run. 


Corrective Action: Exit to the operating system com- 
mand line, and resubmit your program. 
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-409 
Description of Error: sqlexec was not found or was 
not executable by the current user. 


System Action Taken: The statement did not run. 


Corrective Action: Check that your INFORMIXDIR 
environment variable is properly set. Contact your 
System Administrator if you need help with this action. 


-410 
Description of Error: PREPARE statement failed or 
was not executed. 


System Action Taken: The statement was not 
executed. 


Corrective Action: Check that your PREPARE state- 
ment was successfully executed (a failure is often due to 
a syntax error). 


-411 
Description of Error: Attempt to specify both host 
variables and descriptor. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You cannot specify host variables 
in the DECLARE statement and then use the descrip- 
tor option on the OPEN statement (query cursor) or 
the descriptor option on the PUT statement (insert 
cursor). Either remove the host variables from the 
DECLARE statement, or remove references to the 
descriptor in the OPEN or PUT statement. 
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-412 
Description of Error: Command pointer is NULL. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: The statement executed prior to 
the current statement returned an error that was not 
trapped. Reexecute the prior statement(s) and include 
a response to the error code returned. 


-413 
Description of Error: Insert attempted on unopened 
cursor. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Open the cursor before executing 
a PUT statement. 


-414 
Description of Error: Insert attempted on NULL 
cursor. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Make sure you have declared the 
cursor correctly. 


-415 
Description of Error: Data conversion error 
discovered during PUT operation. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: The host variable is incompatible 
with the data type of a column in the database. Choose 
an appropriate host variable or restrict the size of the 
data in the host variable. 
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-416 
Description of Error: USING option with open 
statement is invalid for insert cursor. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You should use the USING option 
with the PUT statement. 


-417 
Description of Error: FLUSH can only be used on 
an insert cursor. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Make sure you are using the 
correct cursor. 


-418 
Description of Error: NULL SQLDA descriptor or 
host variable list encountered. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Make sure you are using the 
correct host variable and descriptor. 


-419 
Description of Error: SQLDATA pointer in SQLDA 
or host variable is null. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the host variable list to 
make sure it is valid. Make sure that memory is prop- 
erly assigned for the SQLDA structure. 
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-500 
Description of Error: Clustered index already exists 
in the table. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Do not create a clustered index 
where one already exists. Alter the existing cluster 
index to NOT CLUSTER before creating a new 
clustered index. 


-501 
Description of Error: Index is already not clustered. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You do not need to alter index to 
NOT CLUSTER. 


-502 
Description of Error: Cannot cluster index. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the C-ISAM error code for 
more information about the problem. 


-503 
Description of Error: Too many tables locked. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Either unlock one or more tables, 
or open the database in exclusive mode. 
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-504 
Description of Error: Attempt to lock a view. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You cannot lock a view. Edit 
your program or statements and remove the request to 
lock the view. 


-505 
Description of Error: Number of columns in 
UPDATE does not match number of VALUES. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Rewrite your RDSQL statement. 


-506 
Description of Error: Do not have permission to 
update all columns. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Obtain permission from the owner 
of the table. 


-507 
Description of Error: Cursor not found. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: This cursor has not been defined. 
Check the spelling of the cursor. 
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-508 
Description of Error: Attempt to rename a tem- 
porary file. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You cannot rename a temporary 
file. Modify your program, or create another table and 
insert to fill the table. 


-509 
Description of Error: Attempt to rename a column 
in a temporary file. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Use an alias to define the column 
name as part of the select statement. 


-1200 
Description of Error: Number is too large for a 
DECIMAL data type. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You have exceeded the range of 
numbers allowed as a decimal data we. Allowable dec- 
imal numbers range from -.1 x 10-1 
to.1 x 10126 


(with 32 significant digits). Check the size of the 
number. 
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-1201 
Description of Error: Number is too small for a 
DECIMAL data type. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You have exceeded the range of 
numbers allowed as a decimal data t¥pe. Allowable dec- 
imal numbers range from -.1 x 10-12 to.1 x 10126 (with 
32 significant digits). Check the size of the number. 


-1202 
Description of Error: An attempt was made to divide 
by zero. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that you are not attempt- 
ing to divide a numerical column type by a character 
column type (for example, 16/Jones) or that the value 
of the divisor does not equal zero. 


-1203 
Description of Error: The values used in a MATCH 
are not both type CHARACTER. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that the values included in 
your MATCH condition are both CHAR types. Use an 
alternate comparison condition for non-CHAR types. 
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-1204 
Description of Error: Invalid year in date. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Acceptable years are 0001 to 9999. 
If two digits are used, RDSQL assumes the year is 19xx. 
Check the value entered in the date field. 


-1205 
Description of Error: Invalid month in date. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Months can be represented as the 
number of the month (l through 12) or the first three 
letters of the name of the month. Check the value 
entered in the date field. 


-1206 
Description of Error: Invalid day in date. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Acceptable days are 01 through 
31. Check the value entered in the date field. 


-1207 
Description of Error: returned by rvalstrO: The 
resulting string (after conversion) does not fit into the 
caller-provided buffer. Converted value does not fit 
into the allotted space. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: The converted value contains too 
many characters to fit into the character buffer passed 
to rvalstrO. Increase the length of the buffer. 
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-1208 
Description of Error: returned by rvaldataO: The 
intended destination type (character) is not the same 
type as the source. There is no conversion from non- 
character values to character values. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that the data types of both 
columns are the same. 


-1209 
Description of Error: Without any delimiters, the 
date does not contain exactly six or eight digits. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You must enter either six or eight 
digits when specifying a data value to represent the 
date. 


-1210 
Description of Error: Date could not be converted to 
month/day/year format. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Dates must be presented as 
month, day, and year (August 4, 1985 is allowed; 
4 August, 1985 is not). Check the sequence of charac- 
ters entered in the date field. 


-1211 
Description of Error: Out of memory. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: You have exceeded the data space 
capacity on your machine. Reduce the complexity of 
your form. 
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-1212 
Description of Error: Date conversion format string 
does not contain a month, day, and year component. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: The FORMAT string used to for- 
mat a DATE field must contain month, day, and year 
components. One of these is missing. 


-1213 
Description of Error: Character to numeric 
conversion error. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that the values in the 
character string contain only ASCII characters 
representing numeric data types. 


-1214 
Description of Error: Value too large to fit in a 
SMALLINT. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Acceptable SMALLINT values 
are whole numbers between -32,767 and 32,767. If a 
larger number is required, you must use the RnSQL 
ALTER TABLE statement to modify the column to 
INTEGER type. 
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-1215 
Description of Error: Value too large to fit in an 
INTEGER. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Acceptable INTEGER values 
are whole numbers between -2,147,483,647 and 
2,147,483,647. If a larger number is required, you must 
use the RDSQL ALTER TABLE statement to modify 
the column to DECIMAL type. 


-1216 
Description of Error: Illegal exponent. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check that the exponent is an 
integer with a value not exceeding 32,767. 


-1217 
Description of Error: The format string is too large. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Reduce the size of the FORMAT 
string (used to format a DATE field) in the form 
specification. 


-1218 
Description of Error: String to date conversion 
error. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Check the format of the DATE 
data type in the DBDATE environment variable. The 
format is illegal. 
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-1226 
Description of Error: Decimal or money value 
exceeds maximum precision. 


System Action Taken: The statement containing the 
error was not processed. 


Corrective Action: Increase the precision of the 
DECIMAL or MONEY field. 
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